diff --git a/internal/backend/tmux/session.go b/internal/backend/tmux/session.go index 7b3a3e8..5f23aa0 100644 --- a/internal/backend/tmux/session.go +++ b/internal/backend/tmux/session.go @@ -227,6 +227,7 @@ func (s *Session) SetContext(ctx string) { s.mu.Lock() defer s.mu.Unlock() s.context = ctx + s.initialPromptSent = false } // GetContext gets the startup context (empty after first Send) diff --git a/roles/conductor.md b/roles/conductor.md index f87c521..5f08066 100644 --- a/roles/conductor.md +++ b/roles/conductor.md @@ -28,16 +28,19 @@ You are NOT allowed to: 2. Read the bead and its existing children (if any) 3. Evaluate completeness: do the children fully cover the goal and acceptance criteria? - If incomplete: add missing child beads, or send QUERY_REQUEST to user for clarification -4. For each ready child bead (dependencies met): +4. Before dispatching parallel implementation beads, verify orthogonality: + - Check that no two concurrently-dispatched beads modify the same files + - If beads overlap, sequence them (add dependency) rather than parallelizing +5. For each ready child bead (dependencies met): - Find the appropriate bot via `list_sessions` by role - Send the bead assignment directly (PROMPT_REQUEST, REVIEW_REQUEST, APPROVAL_REQUEST, etc.) - Mark the child bead `in_progress` -5. As responses arrive: +6. As responses arrive: - On success: mark child bead `closed`, unblock and dispatch dependent children - On rejection: re-assign to the original bot for rework - On blocker: send QUERY_REQUEST to user -6. When all children are `closed`, close the parent bead -7. Send PROMPT_RESPONSE to the user +7. When all children are `closed`, close the parent bead +8. Send PROMPT_RESPONSE to the user ## Response Format diff --git a/workflows/audit.md b/workflows/audit.md new file mode 100644 index 0000000..571555d --- /dev/null +++ b/workflows/audit.md @@ -0,0 +1,26 @@ +--- +name: Audit +description: Code quality assessment of existing code with no changes made +roles: reviewer +--- + +Use this workflow to assess the quality, correctness, or security posture of +existing code without making any changes. Output is a findings report. + +## Decomposition + +| # | Title | Role | Depends On | +|---|------------------------|----------|------------| +| 1 | Audit: | reviewer | — | + +## Handoffs + +None. Findings go directly to the conductor and user. + +## Notes + +- The reviewer must not make any changes to the codebase. +- The output should be a structured findings report, not a pass/fail verdict. +- If findings warrant fixes, track them as separate beads using an appropriate + workflow rather than folding them into this one. +- If any required role is not present in the session, block and report to the user. diff --git a/workflows/bugfix.md b/workflows/bugfix.md new file mode 100644 index 0000000..769cc82 --- /dev/null +++ b/workflows/bugfix.md @@ -0,0 +1,49 @@ +--- +name: Bug Fix +description: Minimal workflow for a well-understood, self-contained bug fix +roles: developer, reviewer, tester +--- + +Use this workflow for bugs where the cause is already known and the fix is +straightforward. No research, no deployment step. + +## Decomposition + +| # | Title | Role | Depends On | +|---|---------------------------|-----------|------------| +| 1 | Fix: | developer | — | +| 2 | Review: | reviewer | 1 | +| 3 | Verify fix: | tester | 2 | + +## Handoffs + +**1 → 2 (developer → reviewer)** +Conductor includes in REVIEW_REQUEST: +- Files modified +- Description of the fix and root cause +- Any edge cases or areas of concern + +**2 rejected → 1 (reviewer → developer)** +Conductor includes in PROMPT_REQUEST: +- Reviewer findings +- Files and locations requiring changes + +**2 → 3 (reviewer approved → tester)** +Conductor includes in APPROVAL_REQUEST: +- Files modified +- Description of the bug and expected correct behavior +- Reviewer findings and resolution summary + +**3 failed → 1 (tester → developer)** +Conductor includes in PROMPT_REQUEST: +- Test failures and reproduction steps +- Files under test + +## Notes + +- The tester's job here is specifically to verify the bug is fixed, not + exhaustive regression testing. +- After rework, the full review and test cycle repeats from step 2. +- If the fix turns out to be non-trivial during implementation, escalate to + the `feature` workflow. +- If any required role is not present in the session, block and report to the user. diff --git a/workflows/doc-research.md b/workflows/doc-research.md new file mode 100644 index 0000000..7077188 --- /dev/null +++ b/workflows/doc-research.md @@ -0,0 +1,41 @@ +--- +name: Documentation (Research Required) +description: Documentation that requires technical investigation before writing +roles: researcher, author, technical-editor +--- + +Use this workflow when documentation cannot be written without first +researching the subject — e.g. a new architecture guide, an unfamiliar +API's reference docs, or documenting a system that is not yet well understood. + +## Decomposition + +| # | Title | Role | Depends On | +|---|------------------------|------------------|------------| +| 1 | Research: | researcher | — | +| 2 | Write: | author | 1 | +| 3 | Edit: | technical-editor | 2 | + +## Handoffs + +**1 → 2 (researcher → author)** +Conductor includes in PROMPT_REQUEST: +- Research findings +- Relevant file paths, APIs, or external references +- Intended audience and purpose of the documentation + +**2 → 3 (author → technical-editor)** +Conductor includes in REVIEW_REQUEST: +- Files written or modified +- Intended audience and purpose of the documentation +- Any sections the author flagged as uncertain + +**3 rejected → 2 (technical-editor → author)** +Conductor includes in PROMPT_REQUEST: +- Editorial findings +- Locations and nature of each issue + +## Notes + +- After rework, the editorial review repeats from step 3. +- If any required role is not present in the session, block and report to the user. diff --git a/workflows/doc.md b/workflows/doc.md new file mode 100644 index 0000000..9f621ad --- /dev/null +++ b/workflows/doc.md @@ -0,0 +1,35 @@ +--- +name: Documentation +description: Write and editorially review documentation +roles: author, technical-editor +--- + +Use this workflow for any documentation task: new guides, reference material, +API docs, README updates, or revisions to existing content. + +## Decomposition + +| # | Title | Role | Depends On | +|---|----------------------|------------------|------------| +| 1 | Write: | author | — | +| 2 | Edit: | technical-editor | 1 | + +## Handoffs + +**1 → 2 (author → technical-editor)** +Conductor includes in REVIEW_REQUEST: +- Files written or modified +- Intended audience and purpose of the documentation +- Any sections the author flagged as uncertain + +**2 rejected → 1 (technical-editor → author)** +Conductor includes in PROMPT_REQUEST: +- Editorial findings +- Locations and nature of each issue + +## Notes + +- After rework, the editorial review repeats from step 2. +- If the author needs technical details from the codebase, that is within scope + of the author role and does not require a separate research bead. +- If any required role is not present in the session, block and report to the user. diff --git a/workflows/feature-research.md b/workflows/feature-research.md new file mode 100644 index 0000000..a04f3dd --- /dev/null +++ b/workflows/feature-research.md @@ -0,0 +1,65 @@ +--- +name: Feature (Research Required) +description: Complex feature where design or technical approach must be established before implementation +roles: researcher, developer, reviewer, tester, devops +--- + +Use this workflow when the implementation approach is unclear, the feature +touches unfamiliar territory, or the bead description lacks sufficient detail +to begin coding directly. + +## Decomposition + +| # | Title | Role | Depends On | +|---|--------------------------|------------|------------| +| 1 | Research: | researcher | — | +| 2 | Implement: | developer | 1 | +| 3 | Review: | reviewer | 2 | +| 4 | Test: | tester | 3 | +| 5 | Deploy: | devops | 4 | + +## Handoffs + +**1 → 2 (researcher → developer)** +Conductor includes in PROMPT_REQUEST: +- Research findings and recommendation +- Chosen approach and rationale +- Relevant file paths, APIs, or external references + +**2 → 3 (developer → reviewer)** +Conductor includes in REVIEW_REQUEST: +- Files modified +- Summary of implementation approach +- Any deviations from the research recommendation + +**3 rejected → 2 (reviewer → developer)** +Conductor includes in PROMPT_REQUEST: +- Reviewer findings +- Files and locations requiring changes + +**3 → 4 (reviewer approved → tester)** +Conductor includes in APPROVAL_REQUEST: +- Files modified +- Reviewer findings and resolution summary +- Acceptance criteria from the original bead + +**4 failed → 2 (tester → developer)** +Conductor includes in PROMPT_REQUEST: +- Test failures and output +- Files under test + +**4 → 5 (tester approved → devops)** +Conductor includes in PROMPT_REQUEST: +- Test results summary +- Files modified +- Any environment or configuration dependencies noted during testing + +## Notes + +- Multiple implementation beads may be dispatched in parallel if they are orthogonal (no shared files). If two beads touch the same files, sequence them with a dependency instead. +- After rework, the full review and test cycle repeats from step 3. +- The research bead should produce a concrete recommendation or design + decision, not an open-ended exploration. Scope it accordingly. +- If research reveals the feature is larger than expected, escalate to + the user before proceeding to implementation. +- If any required role is not present in the session, block and report to the user. diff --git a/workflows/feature-with-docs.md b/workflows/feature-with-docs.md new file mode 100644 index 0000000..55f8360 --- /dev/null +++ b/workflows/feature-with-docs.md @@ -0,0 +1,73 @@ +--- +name: Feature with Documentation +description: Feature development followed by documentation of the new functionality +roles: developer, reviewer, tester, devops, author, technical-editor +--- + +Use this workflow for user-facing features where documentation must ship +alongside the code. + +## Decomposition + +| # | Title | Role | Depends On | +|---|--------------------------|------------------|------------| +| 1 | Implement: | developer | — | +| 2 | Review: | reviewer | 1 | +| 3 | Test: | tester | 2 | +| 4 | Deploy: | devops | 3 | +| 5 | Write: | author | 4 | +| 6 | Edit: | technical-editor | 5 | + +## Handoffs + +**1 → 2 (developer → reviewer)** +Conductor includes in REVIEW_REQUEST: +- Files modified +- Summary of implementation approach +- Any deviations from the original bead description + +**2 rejected → 1 (reviewer → developer)** +Conductor includes in PROMPT_REQUEST: +- Reviewer findings +- Files and locations requiring changes + +**2 → 3 (reviewer approved → tester)** +Conductor includes in APPROVAL_REQUEST: +- Files modified +- Reviewer findings and resolution summary +- Acceptance criteria from the original bead + +**3 failed → 1 (tester → developer)** +Conductor includes in PROMPT_REQUEST: +- Test failures and output +- Files under test + +**3 → 4 (tester approved → devops)** +Conductor includes in PROMPT_REQUEST: +- Test results summary +- Files modified +- Any environment or configuration dependencies noted during testing + +**4 → 5 (devops → author)** +Conductor includes in PROMPT_REQUEST: +- Files modified +- Summary of the feature and its user-facing behavior +- Any deployment notes relevant to documentation + +**5 → 6 (author → technical-editor)** +Conductor includes in REVIEW_REQUEST: +- Files written or modified +- Intended audience and purpose of the documentation +- Any sections the author flagged as uncertain + +**6 rejected → 5 (technical-editor → author)** +Conductor includes in PROMPT_REQUEST: +- Editorial findings +- Locations and nature of each issue + +## Notes + +- After code rework, the full review and test cycle repeats from step 2. +- After doc rework, the editorial review repeats from step 6. +- Multiple implementation beads may be dispatched in parallel if they are orthogonal (no shared files). If two beads touch the same files, sequence them with a dependency instead. +- If any required role is not present in the session, block and report to the user. diff --git a/workflows/feature.md b/workflows/feature.md new file mode 100644 index 0000000..1e13475 --- /dev/null +++ b/workflows/feature.md @@ -0,0 +1,54 @@ +--- +name: Feature +description: Standard feature development with review, testing, and deployment +roles: developer, reviewer, tester, devops +--- + +Use this workflow for well-understood features where requirements are clear +and no upfront research is needed. + +## Decomposition + +| # | Title | Role | Depends On | +|---|--------------------------|-----------|------------| +| 1 | Implement: | developer | — | +| 2 | Review: | reviewer | 1 | +| 3 | Test: | tester | 2 | +| 4 | Deploy: | devops | 3 | + +## Handoffs + +**1 → 2 (developer → reviewer)** +Conductor includes in REVIEW_REQUEST: +- Files modified +- Summary of implementation approach +- Any deviations from the original bead description + +**2 rejected → 1 (reviewer → developer)** +Conductor includes in PROMPT_REQUEST: +- Reviewer findings +- Files and locations requiring changes + +**2 → 3 (reviewer approved → tester)** +Conductor includes in APPROVAL_REQUEST: +- Files modified +- Reviewer findings and resolution summary +- Acceptance criteria from the original bead + +**3 failed → 1 (tester → developer)** +Conductor includes in PROMPT_REQUEST: +- Test failures and output +- Files under test + +**3 → 4 (tester approved → devops)** +Conductor includes in PROMPT_REQUEST: +- Test results summary +- Files modified +- Any environment or configuration dependencies noted during testing + +## Notes + +- Multiple implementation beads may be dispatched in parallel if they are orthogonal (no shared files). If two beads touch the same files, sequence them with a dependency instead. +- After rework, the full review and test cycle repeats from step 2. +- Deployment typically means opening a PR and verifying CI passes. +- If any required role is not present in the session, block and report to the user. diff --git a/workflows/hotfix.md b/workflows/hotfix.md new file mode 100644 index 0000000..1064fca --- /dev/null +++ b/workflows/hotfix.md @@ -0,0 +1,54 @@ +--- +name: Hotfix +description: Urgent bug fix that must be reviewed, tested, and deployed immediately +roles: developer, reviewer, tester, devops +--- + +Use this workflow for production bugs that require an immediate fix and +deployment. The full quality gate still applies — speed does not justify +skipping review or testing. + +## Decomposition + +| # | Title | Role | Depends On | +|---|---------------------------|-----------|------------| +| 1 | Fix: | developer | — | +| 2 | Review: | reviewer | 1 | +| 3 | Verify fix: | tester | 2 | +| 4 | Deploy: | devops | 3 | + +## Handoffs + +**1 → 2 (developer → reviewer)** +Conductor includes in REVIEW_REQUEST: +- Files modified +- Description of the fix and root cause +- Any edge cases or areas of concern + +**2 rejected → 1 (reviewer → developer)** +Conductor includes in PROMPT_REQUEST: +- Reviewer findings +- Files and locations requiring changes + +**2 → 3 (reviewer approved → tester)** +Conductor includes in APPROVAL_REQUEST: +- Files modified +- Description of the bug and expected correct behavior +- Reviewer findings and resolution summary + +**3 failed → 1 (tester → developer)** +Conductor includes in PROMPT_REQUEST: +- Test failures and reproduction steps +- Files under test + +**3 → 4 (tester approved → devops)** +Conductor includes in PROMPT_REQUEST: +- Test results summary +- Files modified +- Target environment and urgency context + +## Notes + +- After rework, the full review and test cycle repeats from step 2. +- Deployment should be expedited but must not bypass CI. +- If any required role is not present in the session, block and report to the user. diff --git a/workflows/incident.md b/workflows/incident.md new file mode 100644 index 0000000..9fc8f60 --- /dev/null +++ b/workflows/incident.md @@ -0,0 +1,73 @@ +--- +name: Incident +description: Production hotfix followed by post-mortem documentation +roles: developer, reviewer, tester, devops, author, technical-editor +--- + +Use this workflow for production incidents: fix and ship the hotfix, then +document what happened, why, and how it was resolved. + +## Decomposition + +| # | Title | Role | Depends On | +|---|---------------------------|------------------|------------| +| 1 | Fix: | developer | — | +| 2 | Review: | reviewer | 1 | +| 3 | Verify fix: | tester | 2 | +| 4 | Deploy: | devops | 3 | +| 5 | Post-mortem: | author | 4 | +| 6 | Edit: | technical-editor | 5 | + +## Handoffs + +**1 → 2 (developer → reviewer)** +Conductor includes in REVIEW_REQUEST: +- Files modified +- Description of the fix and root cause +- Any edge cases or areas of concern + +**2 rejected → 1 (reviewer → developer)** +Conductor includes in PROMPT_REQUEST: +- Reviewer findings +- Files and locations requiring changes + +**2 → 3 (reviewer approved → tester)** +Conductor includes in APPROVAL_REQUEST: +- Files modified +- Description of the bug and expected correct behavior +- Reviewer findings and resolution summary + +**3 failed → 1 (tester → developer)** +Conductor includes in PROMPT_REQUEST: +- Test failures and reproduction steps +- Files under test + +**3 → 4 (tester approved → devops)** +Conductor includes in PROMPT_REQUEST: +- Test results summary +- Files modified +- Target environment and urgency context + +**4 → 5 (devops → author)** +Conductor includes in PROMPT_REQUEST: +- Timeline of the incident and fix +- Root cause as identified by the developer +- Files modified and deployment details + +**5 → 6 (author → technical-editor)** +Conductor includes in REVIEW_REQUEST: +- Files written or modified +- Post-mortem audience (internal team, stakeholders, etc.) +- Any sections the author flagged as uncertain + +**6 rejected → 5 (technical-editor → author)** +Conductor includes in PROMPT_REQUEST: +- Editorial findings +- Locations and nature of each issue + +## Notes + +- After code rework, the full review and test cycle repeats from step 2. +- After post-mortem rework, the editorial review repeats from step 6. +- Deployment should be expedited but must not bypass CI. +- If any required role is not present in the session, block and report to the user. diff --git a/workflows/refactor.md b/workflows/refactor.md new file mode 100644 index 0000000..8cc44eb --- /dev/null +++ b/workflows/refactor.md @@ -0,0 +1,37 @@ +--- +name: Refactor +description: Structural code improvement with no behavior change +roles: developer, reviewer +--- + +Use this workflow for refactoring work: restructuring, renaming, extracting +abstractions, improving readability. No new behavior is introduced, so no +formal testing pass or deployment step is required. + +## Decomposition + +| # | Title | Role | Depends On | +|---|----------------------------|-----------|------------| +| 1 | Refactor: | developer | — | +| 2 | Review: | reviewer | 1 | + +## Handoffs + +**1 → 2 (developer → reviewer)** +Conductor includes in REVIEW_REQUEST: +- Files modified +- Description of structural changes made +- Confirmation that no behavior was changed and existing tests still pass + +**2 rejected → 1 (reviewer → developer)** +Conductor includes in PROMPT_REQUEST: +- Reviewer findings +- Files and locations requiring changes + +## Notes + +- After rework, review repeats from step 2. +- Multiple implementation beads may be dispatched in parallel if they are orthogonal (no shared files). If two beads touch the same files, sequence them with a dependency instead. +- If the refactor reveals bugs or missing tests, those should be tracked as + separate beads rather than folded into this workflow. +- If any required role is not present in the session, block and report to the user. diff --git a/workflows/release.md b/workflows/release.md new file mode 100644 index 0000000..983db31 --- /dev/null +++ b/workflows/release.md @@ -0,0 +1,25 @@ +--- +name: Release +description: Package and ship already-completed, tested work +roles: devops +--- + +Use this workflow when development, review, and testing are complete and the +only remaining work is packaging, tagging, and deploying to production. + +## Decomposition + +| # | Title | Role | Depends On | +|---|-------------------------|--------|------------| +| 1 | Release: | devops | — | + +## Handoffs + +None. Output goes directly to the conductor and user. + +## Notes + +- This workflow assumes all quality gates have already been passed. If there + is any doubt, use `hotfix` or `feature` instead. +- The devops bot should verify CI is green before releasing. +- If any required role is not present in the session, block and report to the user. diff --git a/workflows/research.md b/workflows/research.md new file mode 100644 index 0000000..61c8ebd --- /dev/null +++ b/workflows/research.md @@ -0,0 +1,22 @@ +--- +name: Research +description: Standalone research or investigation task with no implementation +roles: researcher +--- + +Use this workflow when the goal is purely to answer a question, evaluate an +approach, or produce a findings report — with no coding deliverable. + +## Decomposition + +| # | Title | Role | Depends On | +|---|-------------------------|------------|------------| +| 1 | Research: | researcher | — | + +## Notes + +- The output of the research bead should be a written summary delivered to + the conductor, which passes it to the user. +- If the findings suggest follow-on implementation work, the conductor should + report that to the user rather than spawning additional beads unilaterally. +- If any required role is not present in the session, block and report to the user. diff --git a/workflows/review-only.md b/workflows/review-only.md new file mode 100644 index 0000000..63070e1 --- /dev/null +++ b/workflows/review-only.md @@ -0,0 +1,33 @@ +--- +name: Review Only +description: Review and verify existing code with no implementation step +roles: reviewer, tester +--- + +Use this workflow when code already exists and only needs to be reviewed and +verified — e.g. an external PR, a branch written outside the system, or +work submitted for a second opinion. + +## Decomposition + +| # | Title | Role | Depends On | +|---|--------------------------|----------|------------| +| 1 | Review: | reviewer | — | +| 2 | Test: | tester | 1 | + +## Handoffs + +**1 → 2 (reviewer approved → tester)** +Conductor includes in APPROVAL_REQUEST: +- Files under review +- Reviewer findings and resolution summary +- Acceptance criteria or context from the original bead + +**1 rejected → conductor** +Conductor reports findings to the user. No testing is performed on rejected code. + +## Notes + +- If review rejects, the workflow ends. It is the user's responsibility to + arrange rework and resubmit. +- If any required role is not present in the session, block and report to the user. diff --git a/workflows/spike.md b/workflows/spike.md new file mode 100644 index 0000000..f2ecfb8 --- /dev/null +++ b/workflows/spike.md @@ -0,0 +1,29 @@ +--- +name: Spike +description: Time-boxed exploratory investigation to determine whether and how to proceed +roles: researcher +--- + +Use this workflow when the goal is to evaluate an approach, assess feasibility, +or answer a strategic question — not to produce a design or implementation. +The output is a recommendation: proceed, don't proceed, or proceed differently. + +## Decomposition + +| # | Title | Role | Depends On | +|---|------------------------|------------|------------| +| 1 | Spike: | researcher | — | + +## Handoffs + +None. Output goes directly to the conductor and user. + +## Notes + +- The researcher must time-box exploration. If the answer cannot be determined + within reasonable effort, that itself is the finding — report it and stop. +- The output must include a clear recommendation, not an open-ended summary. +- If the recommendation is to proceed, the conductor should report this to the + user and wait for a follow-on bead rather than spawning implementation work + unilaterally. +- If any required role is not present in the session, block and report to the user.