diff --git a/src/aipass/flow/templates/default.md b/src/aipass/flow/templates/default.md new file mode 100644 index 00000000..eb49cd7e --- /dev/null +++ b/src/aipass/flow/templates/default.md @@ -0,0 +1,253 @@ +# FPLAN-{number} - {subject} + +**Created**: {today} +**Branch**: {location} +**Status**: Active +**Type**: Standard Plan + +--- + +## What Are Flow Plans? + +Flow Plans (FPLANs) are for **BUILDING** - autonomous construction of systems, features, modules. + +**This is NOT for:** +- Research or exploration (use agents directly) +- Quick fixes (just do it) +- Discussion or planning (that happens before creating the FPLAN) + +**This IS for:** +- Building features or modules +- Single focused construction tasks +- Sub-plans within a master plan + +--- + +## When to Use This vs Master Plan + +| This (Default) | Master Plan | +|----------------|-------------| +| Single focused task | 3+ phases, complex build | +| Self-contained | Roadmap + multiple sub-plans | +| Quick build | Multi-session project | +| One phase of a master | Entire branch/system build | + +**Need a master plan?** `drone @flow create "subject" master` + +--- + +## Branch Directory Structure + +Use dedicated directories - don't scatter files: + +| Directory | Purpose | +|-----------|---------| +| `apps/` | Code (modules/, handlers/) | +| `tests/` | All test files | +| `tools/` | Utility scripts | +| `artifacts/` | Agent outputs | +| `docs/` | Documentation | + +--- + +## Critical: Branch Manager Role + +**You are the ORCHESTRATOR, not the builder.** + +Your 200k context is precious. Burning it on file reads and code writing risks compaction during autonomous work. Agents have clean context - use them for ALL building. + +| You Do (Orchestrator) | Agents Do (Builders) | +|-----------------------|----------------------| +| Create plans | Write code | +| Give instructions | Run tests | +| Review output | Read/modify files | +| Course correct | Research/exploration | +| Update memories | Heavy lifting | +| Send status emails | Single-task execution | + +**Pattern:** Instruct agent → Wait for completion → Review output → Next step + +--- + +## Seek Branch Expertise + +Don't figure everything out alone. Other branches are domain experts - ask them first. + +**Before building anything that touches another branch's domain:** +```bash +ai_mail send @branch "Question: [topic]" "I'm working on X and need guidance on Y. What's the best approach?" +``` + +**Common examples:** +- Building something with email? Ask @ai_mail how delivery works +- Need routing or @ resolution? Ask @drone +- Unsure about standards? Ask @seed for reference code +- Need persistent storage or search? Ask @memory_bank +- Event-driven behavior? Ask @trigger about their event system +- Dashboard integration? Ask @devpulse about update_section() + +They have deep memory on their systems. A 1-email question saves you hours of guessing. + +--- + +## Notepad + +Keep `notepad.md` in your branch directory as a shared scratchpad during the build. Use it for: +- **Status updates** - Quick progress lines so Patrick can glance without asking +- **Questions for Patrick** - Non-urgent questions that can wait for his next visit +- **Notes to self** - Decisions made, things to revisit, gotchas discovered + +Update it as you work - lightweight, not formal. Patrick checks it when he wants to, skips it when he's busy. + +--- + +## Command Reference + +When unsure about syntax, use `--help`: + +```bash +# Flow - Plan management +drone @flow create . "subject" # Create plan (. = current dir) +drone @flow close FPLAN-XXXX # Close plan +drone @flow list # List active plans +drone @flow --help # Full help + +# Seed - Quality gates +drone @seed checklist # 10-point check on file +drone @seed audit @branch # Full branch audit +drone @seed --help # Full help + +# AI_Mail - Status updates +drone @ai_mail send @dev_central "Subject" "Message" +drone @ai_mail --help # Full help + +# Discovery +drone systems # All available modules +drone list @branch # Commands for branch +``` + +--- + +## Planning Phase + +### Goal +[What do you want to achieve? Specific end state.] + +### Approach +[How will agents tackle this? What instructions will they need?] + +### Reference Documents +[List any planning docs, specs, or examples to reference] + +--- + +## Agent Preparation (Before Deploying) + +Agents can't work blind. They need context before they build. + +**Your Prep Work (as orchestrator):** +1. [ ] Know where agent will work (branch path, key directories) +2. [ ] Identify files agent needs to reference or modify +3. [ ] Gather any specs, planning docs, or examples to include +4. [ ] Prepare COMPLETE instructions (agents are stateless) + +**Agent's First Task (context building):** +- Agent should explore/read relevant files BEFORE writing code +- "First, read X and Y to understand the current structure" +- "Look at Z for the pattern to follow" +- Context-first, build-second + +**What Agents DON'T Have:** +- No prior conversation history +- No memory files loaded automatically +- No knowledge of other branches +- Only what you put in their instructions + +**Your instructions determine success - be thorough and specific.** + +--- + +## Agent Instructions Template +``` +You are working at [BRANCH_PATH]. + +TASK: [Specific single task] + +CONTEXT: +- [What they need to know] +- Reference: [planning docs, existing code to study] +- First, READ the relevant files to understand current structure + +DELIVERABLES: +- [Specific file or output expected] +- Tests → tests/ +- Reports/logs → artifacts/reports/ or artifacts/logs/ + +CONSTRAINTS: +- Follow Seed standards (3-layer architecture) +- Do NOT modify files outside your task scope +- CROSS-BRANCH: Never modify other branches' files unless explicitly authorized by DEV_CENTRAL +- 2-ATTEMPT RULE: If something fails twice, note the issue and move on +- Do NOT go down rabbit holes debugging + +WHEN COMPLETE: +- Verify code runs without syntax errors +- List files created/modified +- Note any issues encountered (with what was attempted) +``` + +--- + +## Execution Log + +### {today} +- [ ] Created FPLAN-{number} +- [ ] Agent deployed for: [task] +- [ ] Agent completed: [outcome] +- [ ] Seed checklist passed: [file] +- [ ] Memories updated + +**Log Pattern:** Task → Agent → Outcome → Quality check → Next + +**If production stops (critical blocker):** +```bash +drone @ai_mail send @dev_central "PRODUCTION STOPPED: FPLAN-{number}" "Issue: [description]. Attempted: [what was tried]. Awaiting guidance." +``` + +--- + +## Notes + +[Working notes, issues encountered, decisions made] + +--- + +## Completion Checklist + +### Before Closing + +- [ ] All goals achieved +- [ ] Agent output reviewed and verified +- [ ] Seed checklist on new code: `drone @seed checklist ` +- [ ] Branch memories updated: + - [ ] `BRANCH.local.json` - session/work log + - [ ] `BRANCH.observations.json` - patterns learned (if any) +- [ ] README.md updated (if build changed status/capabilities) +- [ ] Status email sent to DEV_CENTRAL: + ```bash + drone @ai_mail send @dev_central "FPLAN-{number} Complete" "Summary of what was done, any issues, outcomes" + ``` + +**Completion Order:** Memories → README → Email (README before email - don't report complete with stale docs) + +### Definition of Done +[What specifically defines complete for this plan?] + +--- + +## Close Command + +When all boxes checked: +```bash +drone @flow close FPLAN-{number} +``` diff --git a/src/aipass/flow/templates/master.md b/src/aipass/flow/templates/master.md new file mode 100644 index 00000000..695aff4f --- /dev/null +++ b/src/aipass/flow/templates/master.md @@ -0,0 +1,514 @@ +# FPLAN-{number} - {subject} (MASTER PLAN) + +**Created**: {today} +**Branch**: {location} +**Status**: Active +**Type**: Master Plan (Multi-Phase) + +--- + +## What Are Flow Plans? + +Flow Plans (FPLANs) are for **BUILDING** - autonomous construction of systems, features, modules. They're the structured way to execute work without constant human oversight. + +**This is NOT for:** +- Research or exploration (use agents directly) +- Quick fixes (just do it) +- Discussion or planning (that happens before creating the FPLAN) + +**This IS for:** +- Building new branches/modules +- Implementing features +- Multi-phase construction projects +- Autonomous execution + +--- + +## Master Plan vs Default Plan + +| | Master Plan | Default Plan | +|---|-------------|--------------| +| **Use when** | 3+ phases, complex build | Single focused task | +| **Structure** | Roadmap + sub-plans | Self-contained | +| **Phases** | Multiple, sequential | One | +| **Sub-plans** | Yes, one per phase | No | +| **Typical use** | Build entire branch | One phase of master | + +**Pattern:** +``` +Master Plan (roadmap) +├── Sub-plan Phase 1 (default template) +├── Sub-plan Phase 2 (default template) +├── Sub-plan Phase 3 (default template) +└── Sub-plan Phase 4 (default template) +``` + +**How to start:** +1. DEV_CENTRAL provides planning doc or instructions +2. Branch manager reads and understands scope +3. Branch manager creates master plan: `drone @flow create . "Build X" master` +4. Branch manager fills in phases, then executes autonomously + +--- + +## Critical: Branch Manager Role + +**You are the ORCHESTRATOR, not the builder.** + +Your 200k context is precious. Burning it on file reads and code writing risks compaction during autonomous work. Agents have clean context - use them for ALL building. + +| You Do (Orchestrator) | Agents Do (Builders) | +|-----------------------|----------------------| +| Create plans & sub-plans | Write code | +| Define phases | Run tests | +| Give agent instructions | Read/modify files | +| Review agent output | Research/exploration | +| Course correct | Heavy lifting | +| Update memories | Single-task execution | +| Send status emails | Build deliverables | +| Track phase progress | Quality checks on code | + +**Master Plan Pattern:** Define all phases → Create sub-plan for Phase 1 → Deploy agent → Review → Close sub-plan → Email update → Next phase + +--- + +## Seek Branch Expertise + +Don't figure everything out alone. Other branches are domain experts - ask them first. + +**Before building anything that touches another branch's domain:** +```bash +ai_mail send @branch "Question: [topic]" "I'm working on X and need guidance on Y. What's the best approach?" +``` + +**Common examples:** +- Building something with email? Ask @ai_mail how delivery works +- Need routing or @ resolution? Ask @drone +- Unsure about standards? Ask @seed for reference code +- Need persistent storage or search? Ask @memory_bank +- Event-driven behavior? Ask @trigger about their event system +- Dashboard integration? Ask @devpulse about update_section() + +They have deep memory on their systems. A 1-email question saves you hours of guessing. For master plans spanning multiple domains, identify which branches to consult during phase definitions. + +--- + +## Notepad + +Keep `notepad.md` in your branch directory as a shared scratchpad during the build. Use it for: +- **Status updates** - Quick progress lines so Patrick can glance without asking +- **Questions for Patrick** - Non-urgent questions that can wait for his next visit +- **Notes to self** - Decisions made, things to revisit, gotchas discovered + +Update it as you work - lightweight, not formal. Patrick checks it when he wants to, skips it when he's busy. Low friction both ways. + +```bash +# Create it at plan start +echo "# Notepad - FPLAN-{number}" > notepad.md +``` + +--- + +## Command Reference + +When unsure about syntax, use `--help`: + +```bash +# Flow - Plan management +drone @flow create . "Phase X: subject" # Create sub-plan (. = current dir) +drone @flow create . "subject" master # Create master plan +drone @flow close FPLAN-XXXX # Close plan +drone @flow list # List active plans +drone @flow status # Plan status +drone @flow --help # Full help + +# Seed - Quality gates +drone @seed checklist # 10-point check on file +drone @seed audit @branch # Full branch audit (before master close) +drone @seed --help # Full help + +# AI_Mail - Status updates +drone @ai_mail send @dev_central "Subject" "Message" +drone @ai_mail inbox # Check your inbox +drone @ai_mail --help # Full help + +# Discovery +drone systems # All available modules +drone list @branch # Commands for branch +``` + +--- + +## What is a Master Plan? + +Master Plans are for **complex multi-phase projects**. You define all phases upfront, then create focused sub-plans for each phase. + +**When to use:** +- 3+ distinct sequential phases +- Work spanning multiple sessions +- Need clear phase completion milestones +- Complex builds requiring sustained focus + +**Pattern:** Master Plan = Roadmap | Sub-Plans = Focused Execution + +--- + +## Project Overview + +### Goal +[What is the end state when ALL phases complete?] + +### Reference Documentation +[List planning docs, specs, existing code to reference] + +### Success Criteria +[What defines DONE for the entire project?] + +--- + +## Branch Directory Structure + +Every branch has dedicated directories. Use them correctly: + +``` +branch/ +├── apps/ # Code (modules/, handlers/) +├── tests/ # All test files go here +├── tools/ # Utility scripts, helpers +├── artifacts/ # Agent outputs (reports, logs) +├── docs/ # Documentation +└── logs/ # Execution logs +``` + +**Rules:** +- Tests → `tests/` (not root, not random locations) +- Tools/scripts → `tools/` +- Agent artifacts → `artifacts/` +- Create subdirs if needed: `mkdir -p artifacts/reports artifacts/logs` +- **Never delete** - DEV_CENTRAL manages cleanup +- Future: artifacts auto-roll to Memory Bank + +--- + +## Phase Definitions + +Define ALL phases before starting work: + +### Phase 1: [Name] +**Goal:** [What this phase accomplishes] +**Agent Task:** [What the agent will build] +**Deliverables:** [Files/outputs expected] + +### Phase 2: [Name] +**Goal:** [What this phase accomplishes] +**Agent Task:** [What the agent will build] +**Deliverables:** [Files/outputs expected] + +### Phase 3: [Name] +**Goal:** [What this phase accomplishes] +**Agent Task:** [What the agent will build] +**Deliverables:** [Files/outputs expected] + +### Phase 4: [Name] +**Goal:** [What this phase accomplishes] +**Agent Task:** [What the agent will build] +**Deliverables:** [Files/outputs expected] + +[Add more phases as needed] + +--- + +## Execution Philosophy + +### Autonomous Power-Through + +Master plans are for **autonomous execution**. Don't halt production every phase waiting for DEV_CENTRAL review. + +**The Pattern:** +- Power through all phases +- Accumulate issues as you go +- Deal with issues at the end +- DEV_CENTRAL reviews final result, not every step + +**Why this works:** +- Context is precious - don't burn it chasing bugs +- Complete picture reveals which issues actually matter +- Many "bugs" resolve themselves when later phases complete +- DEV_CENTRAL time is for decisions, not babysitting + +### The 2-Attempt Rule + +When agent encounters an issue: + +``` +Attempt 1 → Failed? + ↓ +Attempt 2 → Failed? + ↓ +STOP. Mark as issue. Move on. +``` + +**Do NOT:** +- Try 5 different approaches +- Go down rabbit holes +- Burn context debugging +- Stop production for every error + +**DO:** +- Note the issue clearly +- Note what was tried +- Move to next task +- Let branch manager decide priority + +### Critical vs Non-Critical Issues + +When you see an issue, decide: + +| Question | If YES → | If NO → | +|----------|----------|---------| +| Does this block ALL future phases? | STOP. Investigate. | Continue. | +| Can the system work around this? | Continue. | STOP. Investigate. | +| Is this a syntax/import error? | Quick fix, continue. | - | +| Is this a logic/design problem? | Note it. Continue. | - | + +**Critical (stop production):** +- Core module won't import at all +- Database/file system inaccessible +- Fundamental architecture wrong + +**Non-critical (note and continue):** +- One command throws error but others work +- Registry not updating properly +- Edge case not handled +- Test failing but code runs + +**Pattern:** Note issue → Continue building → Fix at end with complete picture + +### False Positives Awareness + +Seed audits are helpful but not infallible. + +**When Seed flags something:** +1. Check if the code is actually correct from your understanding +2. If you're confident it's right → mark as false positive, move on +3. If you're unsure → note it, continue, review later + +**Don't stop production for:** +- Style preferences (comments, spacing) +- Patterns that differ from Seed's but still work +- Checks that don't apply to your context + +### Forward Momentum Summary +- **Don't stop to fix bugs during phases** - Note them, keep moving +- **Get complete picture first** - All phases done, THEN systematic fixes +- **Prevents:** Bug-fixing rabbit holes, premature optimization, scope creep +- **DEV_CENTRAL reviews at END** - not every phase + +### Production Stop Protocol + +If something causes production to STOP (critical blocker), **immediately email DEV_CENTRAL**: + +```bash +drone @ai_mail send @dev_central "PRODUCTION STOPPED: FPLAN-{number}" "Phase X halted. Issue: [description]. Attempted: [what was tried]. Awaiting guidance." +``` + +**Never leave a branch stopped without reporting.** DEV_CENTRAL needs visibility into all work. + +### Monitoring Resources + +For quick status checks and debugging, these resources are available: + +| Resource | Location | Purpose | +|----------|----------|---------| +| Branch logs | `logs/` directory | Local execution logs | +| JSON tree | `apps/json_templates/` | Module firing status | +| Prax monitor | `drone @prax monitor` | Real-time system events | +| Seed audit | `drone @seed audit @branch` | Code quality check | + +Use these when you need to confirm status or investigate issues. + +### Agent Deployment Per Phase +Each phase = focused agent deployment: +1. Create sub-plan: `drone @flow create . "Phase X: [name]"` +2. Write agent instructions in sub-plan +3. Deploy agent with single-task focus +4. Review agent output (don't rebuild yourself) +5. Seed checklist on new code +6. Close sub-plan +7. Update memories +8. Email status to @dev_central +9. Next phase + +### Agent Preparation (Before Deploying) + +Agents can't work blind. They need context before they build. + +**Your Prep Work (as orchestrator):** +1. [ ] Know where agent will work (branch path, key directories) +2. [ ] Identify files agent needs to reference or modify +3. [ ] Gather any specs, planning docs, or examples to include +4. [ ] Prepare COMPLETE instructions (agents are stateless) + +**Agent's First Task (context building):** +- Agent should explore/read relevant files BEFORE writing code +- "First, read X and Y to understand the current structure" +- "Look at Z for the pattern to follow" +- Context-first, build-second + +**What Agents DON'T Have:** +- No prior conversation history +- No memory files loaded automatically +- No knowledge of other branches +- Only what you put in their instructions + +**Your instructions determine success - be thorough and specific.** + +### Agent Instructions Template +``` +You are working at [BRANCH_PATH]. + +TASK: [Specific single task for this phase] + +CONTEXT: +- [What they need to know] +- Reference: [planning docs, existing code to study] +- First, READ the relevant files to understand current structure + +DELIVERABLES: +- [Specific file or output expected] +- Tests → tests/ +- Reports/logs → artifacts/reports/ or artifacts/logs/ + +CONSTRAINTS: +- Follow Seed standards (3-layer architecture: apps/modules/handlers) +- Do NOT modify files outside your task scope +- CROSS-BRANCH: Never modify other branches' files unless explicitly authorized by DEV_CENTRAL in the planning doc +- 2-ATTEMPT RULE: If something fails twice, note the issue and move on +- Do NOT go down rabbit holes debugging + +WHEN COMPLETE: +- Verify code runs without syntax errors +- List files created/modified +- Note any issues encountered (with what was attempted) +``` + +--- + +## Phase Tracking + +### Phase 1: [Name] +- [ ] Sub-plan created: FPLAN-____ +- [ ] Agent deployed +- [ ] Agent completed +- [ ] Output reviewed +- [ ] Seed checklist passed +- [ ] Sub-plan closed +- [ ] Memories updated +- [ ] Email sent to @dev_central +- **Status:** Pending / In Progress / Complete +- **Notes:** [Outcomes, issues, adjustments] + +### Phase 2: [Name] +- [ ] Sub-plan created: FPLAN-____ +- [ ] Agent deployed +- [ ] Agent completed +- [ ] Output reviewed +- [ ] Seed checklist passed +- [ ] Sub-plan closed +- [ ] Memories updated +- [ ] Email sent to @dev_central +- **Status:** Pending / In Progress / Complete +- **Notes:** [Outcomes, issues, adjustments] + +### Phase 3: [Name] +- [ ] Sub-plan created: FPLAN-____ +- [ ] Agent deployed +- [ ] Agent completed +- [ ] Output reviewed +- [ ] Seed checklist passed +- [ ] Sub-plan closed +- [ ] Memories updated +- [ ] Email sent to @dev_central +- **Status:** Pending / In Progress / Complete +- **Notes:** [Outcomes, issues, adjustments] + +### Phase 4: [Name] +- [ ] Sub-plan created: FPLAN-____ +- [ ] Agent deployed +- [ ] Agent completed +- [ ] Output reviewed +- [ ] Seed checklist passed +- [ ] Sub-plan closed +- [ ] Memories updated +- [ ] Email sent to @dev_central +- **Status:** Pending / In Progress / Complete +- **Notes:** [Outcomes, issues, adjustments] + +[Copy template for additional phases] + +--- + +## Issues Log + +Track issues here as you encounter them. Don't fix during build - log and continue. + +| Phase | Issue | Severity | Attempted | Status | +|-------|-------|----------|-----------|--------| +| 1 | [description] | Low/Med/High | [what was tried] | Open/Resolved | +| 2 | [description] | Low/Med/High | [what was tried] | Open/Resolved | + +**Severity Guide:** +- **High:** Blocks future phases, must fix before continuing +- **Med:** Affects functionality but can work around +- **Low:** Cosmetic, edge case, or false positive + +**End of Build:** Review this log. Tackle High→Med→Low. Some Low issues may not need fixing. + +--- + +## Master Plan Notes + +**Cross-Phase Patterns:** +[Patterns discovered that span multiple phases] + +**Blockers & Resolutions:** +[Significant blockers and how resolved] + +**Adjustments:** +[Changes to planned phases - scope changes, phases added/merged] + +--- + +## Final Completion Checklist + +### Before Closing Master Plan + +- [ ] All phases complete +- [ ] All sub-plans closed +- [ ] Issues Log reviewed - High/Med issues addressed +- [ ] Full branch audit: `drone @seed audit @branch` +- [ ] Branch memories updated: + - [ ] `BRANCH.local.json` - full session log + - [ ] `BRANCH.observations.json` - patterns learned +- [ ] README.md updated (status, architecture, API - if build changed capabilities) +- [ ] Artifacts reviewed (DEV_CENTRAL manages cleanup) +- [ ] Final email to DEV_CENTRAL: + ```bash + drone @ai_mail send @dev_central "FPLAN-{number} MASTER COMPLETE" "Full build summary: phases completed, deliverables, remaining issues (if any)" + ``` + +**Completion Order:** Memories → README → Email (README before email - don't report complete with stale docs) + +**Note:** DEV_CENTRAL will perform their own Seed audit for visibility into the work. + +### Definition of Done +[What specifically defines the project complete?] + +--- + +## Close Command + +When ALL phases complete and checklist done: +```bash +drone @flow close FPLAN-{number} +```