@cluesmith/codev 3.0.2 → 3.0.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/agent-farm/cli.d.ts.map +1 -1
- package/dist/agent-farm/cli.js +44 -0
- package/dist/agent-farm/cli.js.map +1 -1
- package/dist/agent-farm/commands/attach.d.ts.map +1 -1
- package/dist/agent-farm/commands/attach.js +2 -117
- package/dist/agent-farm/commands/attach.js.map +1 -1
- package/dist/agent-farm/commands/dev.d.ts +20 -0
- package/dist/agent-farm/commands/dev.d.ts.map +1 -0
- package/dist/agent-farm/commands/dev.js +124 -0
- package/dist/agent-farm/commands/dev.js.map +1 -0
- package/dist/agent-farm/commands/setup.d.ts +27 -0
- package/dist/agent-farm/commands/setup.d.ts.map +1 -0
- package/dist/agent-farm/commands/setup.js +55 -0
- package/dist/agent-farm/commands/setup.js.map +1 -0
- package/dist/agent-farm/commands/spawn-worktree.d.ts +21 -2
- package/dist/agent-farm/commands/spawn-worktree.d.ts.map +1 -1
- package/dist/agent-farm/commands/spawn-worktree.js +42 -4
- package/dist/agent-farm/commands/spawn-worktree.js.map +1 -1
- package/dist/agent-farm/commands/spawn.d.ts.map +1 -1
- package/dist/agent-farm/commands/spawn.js +30 -15
- package/dist/agent-farm/commands/spawn.js.map +1 -1
- package/dist/agent-farm/commands/status.d.ts.map +1 -1
- package/dist/agent-farm/commands/status.js +4 -1
- package/dist/agent-farm/commands/status.js.map +1 -1
- package/dist/agent-farm/commands/stop.d.ts.map +1 -1
- package/dist/agent-farm/commands/stop.js +15 -8
- package/dist/agent-farm/commands/stop.js.map +1 -1
- package/dist/agent-farm/commands/workspace-add-architect.d.ts +18 -0
- package/dist/agent-farm/commands/workspace-add-architect.d.ts.map +1 -0
- package/dist/agent-farm/commands/workspace-add-architect.js +54 -0
- package/dist/agent-farm/commands/workspace-add-architect.js.map +1 -0
- package/dist/agent-farm/db/index.d.ts.map +1 -1
- package/dist/agent-farm/db/index.js +54 -1
- package/dist/agent-farm/db/index.js.map +1 -1
- package/dist/agent-farm/db/migrate.js +2 -2
- package/dist/agent-farm/db/migrate.js.map +1 -1
- package/dist/agent-farm/db/schema.d.ts +1 -1
- package/dist/agent-farm/db/schema.d.ts.map +1 -1
- package/dist/agent-farm/db/schema.js +3 -2
- package/dist/agent-farm/db/schema.js.map +1 -1
- package/dist/agent-farm/db/types.d.ts +7 -2
- package/dist/agent-farm/db/types.d.ts.map +1 -1
- package/dist/agent-farm/db/types.js +2 -0
- package/dist/agent-farm/db/types.js.map +1 -1
- package/dist/agent-farm/lib/builder-lookup.d.ts +26 -0
- package/dist/agent-farm/lib/builder-lookup.d.ts.map +1 -0
- package/dist/agent-farm/lib/builder-lookup.js +103 -0
- package/dist/agent-farm/lib/builder-lookup.js.map +1 -0
- package/dist/agent-farm/servers/tower-instances.d.ts +20 -1
- package/dist/agent-farm/servers/tower-instances.d.ts.map +1 -1
- package/dist/agent-farm/servers/tower-instances.js +260 -16
- package/dist/agent-farm/servers/tower-instances.js.map +1 -1
- package/dist/agent-farm/servers/tower-messages.d.ts +10 -1
- package/dist/agent-farm/servers/tower-messages.d.ts.map +1 -1
- package/dist/agent-farm/servers/tower-messages.js +137 -7
- package/dist/agent-farm/servers/tower-messages.js.map +1 -1
- package/dist/agent-farm/servers/tower-routes.d.ts.map +1 -1
- package/dist/agent-farm/servers/tower-routes.js +97 -31
- package/dist/agent-farm/servers/tower-routes.js.map +1 -1
- package/dist/agent-farm/servers/tower-terminals.d.ts +17 -1
- package/dist/agent-farm/servers/tower-terminals.d.ts.map +1 -1
- package/dist/agent-farm/servers/tower-terminals.js +78 -29
- package/dist/agent-farm/servers/tower-terminals.js.map +1 -1
- package/dist/agent-farm/servers/tower-tunnel.d.ts.map +1 -1
- package/dist/agent-farm/servers/tower-tunnel.js +3 -2
- package/dist/agent-farm/servers/tower-tunnel.js.map +1 -1
- package/dist/agent-farm/servers/tower-types.d.ts +18 -6
- package/dist/agent-farm/servers/tower-types.d.ts.map +1 -1
- package/dist/agent-farm/state.d.ts +50 -4
- package/dist/agent-farm/state.d.ts.map +1 -1
- package/dist/agent-farm/state.js +118 -12
- package/dist/agent-farm/state.js.map +1 -1
- package/dist/agent-farm/types.d.ts +28 -0
- package/dist/agent-farm/types.d.ts.map +1 -1
- package/dist/agent-farm/utils/agent-names.d.ts +5 -30
- package/dist/agent-farm/utils/agent-names.d.ts.map +1 -1
- package/dist/agent-farm/utils/agent-names.js +5 -54
- package/dist/agent-farm/utils/agent-names.js.map +1 -1
- package/dist/agent-farm/utils/architect-name.d.ts +37 -0
- package/dist/agent-farm/utils/architect-name.d.ts.map +1 -0
- package/dist/agent-farm/utils/architect-name.js +63 -0
- package/dist/agent-farm/utils/architect-name.js.map +1 -0
- package/dist/agent-farm/utils/config.d.ts +19 -0
- package/dist/agent-farm/utils/config.d.ts.map +1 -1
- package/dist/agent-farm/utils/config.js +16 -0
- package/dist/agent-farm/utils/config.js.map +1 -1
- package/dist/agent-farm/utils/git.d.ts +29 -0
- package/dist/agent-farm/utils/git.d.ts.map +1 -0
- package/dist/agent-farm/utils/git.js +38 -0
- package/dist/agent-farm/utils/git.js.map +1 -0
- package/dist/agent-farm/utils/shell.d.ts +13 -0
- package/dist/agent-farm/utils/shell.d.ts.map +1 -1
- package/dist/agent-farm/utils/shell.js +28 -0
- package/dist/agent-farm/utils/shell.js.map +1 -1
- package/dist/commands/adopt.d.ts.map +1 -1
- package/dist/commands/adopt.js +5 -0
- package/dist/commands/adopt.js.map +1 -1
- package/dist/commands/consult/index.d.ts.map +1 -1
- package/dist/commands/consult/index.js +2 -0
- package/dist/commands/consult/index.js.map +1 -1
- package/dist/commands/init.d.ts.map +1 -1
- package/dist/commands/init.js +5 -0
- package/dist/commands/init.js.map +1 -1
- package/package.json +5 -5
- package/skeleton/protocols/air/builder-prompt.md +6 -0
- package/skeleton/protocols/air/consult-types/impl-review.md +6 -0
- package/skeleton/protocols/air/consult-types/pr-review.md +6 -0
- package/skeleton/protocols/air/prompts/implement.md +6 -0
- package/skeleton/protocols/air/protocol.md +4 -0
- package/skeleton/protocols/aspir/builder-prompt.md +19 -3
- package/skeleton/protocols/aspir/consult-types/plan-review.md +6 -0
- package/skeleton/protocols/aspir/consult-types/spec-review.md +6 -0
- package/skeleton/protocols/aspir/prompts/specify.md +6 -0
- package/skeleton/protocols/aspir/protocol.md +4 -0
- package/skeleton/protocols/bugfix/consult-types/impl-review.md +44 -37
- package/skeleton/protocols/bugfix/consult-types/pr-review.md +65 -40
- package/skeleton/protocols/spir/builder-prompt.md +19 -3
- package/skeleton/protocols/spir/consult-types/plan-review.md +6 -0
- package/skeleton/protocols/spir/consult-types/spec-review.md +6 -0
- package/skeleton/protocols/spir/prompts/specify.md +6 -0
- package/skeleton/protocols/spir/protocol.md +4 -0
|
@@ -37,6 +37,10 @@ AIR is a minimal protocol for implementing small features (< 300 LOC) where the
|
|
|
37
37
|
- Architectural changes → use **SPIR**
|
|
38
38
|
- Complex features with multiple phases → use **SPIR** or **ASPIR**
|
|
39
39
|
|
|
40
|
+
## Baked Decisions (Optional)
|
|
41
|
+
|
|
42
|
+
When filing an issue for AIR, you can pin architectural decisions you don't want the builder or CMAP reviewers to re-litigate. Include a `## Baked Decisions` section (any heading level is fine) anywhere in the issue body. Useful categories: language, framework, deployment shape, key dependencies, decisions deferred to a later spec. The builder will treat each listed item as fixed during implementation; CMAP reviewers will not propose alternatives unless the implementation itself fails to honor a stated decision. Leave the section out for issues where you want the builder to explore freely — absence is the no-op default. You can amend or rescind a baked decision at any time by updating the issue and respawning, or by sending the builder a direct instruction via `afx send`.
|
|
43
|
+
|
|
40
44
|
## Protocol Phases
|
|
41
45
|
|
|
42
46
|
### I - Implement
|
|
@@ -30,6 +30,12 @@ You are running in STRICT mode. This means:
|
|
|
30
30
|
Follow the ASPIR protocol: `codev/protocols/aspir/protocol.md`
|
|
31
31
|
Read and internalize the protocol before starting any work.
|
|
32
32
|
|
|
33
|
+
## Baked Decisions
|
|
34
|
+
|
|
35
|
+
If the issue body contains a section named "Baked Decisions" (any heading level, case-insensitive), treat its contents as fixed architectural decisions baked in by the architect. Do not autonomously override them in your spec, plan, or implementation. If you discover a serious reason to question a baked decision, surface that concern to the architect via `afx send` rather than relitigating it inside the spec/plan/review.
|
|
36
|
+
|
|
37
|
+
If the architect's baked-decisions section contains internal contradictions (e.g., two different language choices), do not pick one — pause, flag the contradiction to the architect via `afx send`, and wait for resolution before proceeding.
|
|
38
|
+
|
|
33
39
|
{{#if spec}}
|
|
34
40
|
## Spec
|
|
35
41
|
Read the specification at: `{{spec.path}}`
|
|
@@ -53,13 +59,23 @@ Follow the implementation plan at: `{{plan.path}}`
|
|
|
53
59
|
{{task_text}}
|
|
54
60
|
{{/if}}
|
|
55
61
|
|
|
56
|
-
##
|
|
62
|
+
## PR Strategy
|
|
63
|
+
|
|
64
|
+
**Do not autonomously open a PR per implementation phase.** Plan phases ship as git commits within a single PR, not as separate PRs. The plan's instruction that "each phase commits independently" refers to git commits, not PRs.
|
|
65
|
+
|
|
66
|
+
By default, the PR is opened during/after the final implement phase, with all phase-commits already on the branch.
|
|
67
|
+
|
|
68
|
+
### Architect-requested PRs
|
|
69
|
+
|
|
70
|
+
The architect MAY request a PR at any point — for spec review, mid-implementation feedback, slicing a large spec into shippable PRs, etc. When the architect explicitly asks for a PR earlier (or for additional PRs), follow that direction. The prohibition is specifically on the *builder* autonomously deciding to open per-phase PRs without architect request.
|
|
71
|
+
|
|
72
|
+
### Multi-PR Mechanics (when the architect requests sequential PRs)
|
|
57
73
|
|
|
58
|
-
Your worktree is persistent — it survives across PR merges.
|
|
74
|
+
Your worktree is persistent — it survives across PR merges. When the architect asks for sequential PRs (e.g., to slice a large spec into shippable pieces), use this loop:
|
|
59
75
|
|
|
60
76
|
1. Cut a branch, open a PR, wait for merge
|
|
61
77
|
2. After merge: `git fetch origin main && git checkout -b <next-branch> origin/main`
|
|
62
|
-
3. Continue to the next
|
|
78
|
+
3. Continue to the next slice, open another PR
|
|
63
79
|
|
|
64
80
|
**Important**: Do NOT run `git checkout main` — git worktrees cannot check out a branch that's checked out elsewhere. Always branch off `origin/main` via fetch.
|
|
65
81
|
|
|
@@ -3,6 +3,12 @@
|
|
|
3
3
|
## Context
|
|
4
4
|
You are reviewing an implementation plan during the Plan phase. The spec has been approved - now you must evaluate whether the plan adequately describes HOW to implement it.
|
|
5
5
|
|
|
6
|
+
## Baked Decisions
|
|
7
|
+
|
|
8
|
+
If the issue body or the approved spec's Constraints section includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed (this extends the existing "don't re-litigate spec decisions" rule with explicit baked-decision language). Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns; reserve `REQUEST_CHANGES` for the case where the plan **fails to honor** a stated baked decision — that is a real defect.
|
|
9
|
+
|
|
10
|
+
If the baked decisions themselves contain contradictions, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding.
|
|
11
|
+
|
|
6
12
|
## Focus Areas
|
|
7
13
|
|
|
8
14
|
1. **Spec Coverage**
|
|
@@ -3,6 +3,12 @@
|
|
|
3
3
|
## Context
|
|
4
4
|
You are reviewing a feature specification during the Specify phase. Your role is to ensure the spec is complete, correct, and feasible before it moves to human approval.
|
|
5
5
|
|
|
6
|
+
## Baked Decisions
|
|
7
|
+
|
|
8
|
+
If the issue body or the spec's Constraints section includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns about a baked decision (the architect decides whether to rescind it); reserve `REQUEST_CHANGES` for the case where the spec **fails to honor** a stated baked decision — that is a real defect.
|
|
9
|
+
|
|
10
|
+
If the baked decisions themselves contain contradictions (e.g., two different language choices), do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding.
|
|
11
|
+
|
|
6
12
|
## Focus Areas
|
|
7
13
|
|
|
8
14
|
1. **Completeness**
|
|
@@ -31,6 +31,12 @@ ls codev/specs/{{project_id}}-*.md
|
|
|
31
31
|
|
|
32
32
|
**If no spec exists:** Proceed to Step 1 below.
|
|
33
33
|
|
|
34
|
+
### 0.5 Baked Decisions
|
|
35
|
+
|
|
36
|
+
Before exploring solution approaches, check the issue body for a section named "Baked Decisions" (any heading level, case-insensitive). If present, copy its content verbatim into the spec's Constraints section and treat each item as fixed. Do not autonomously relitigate the architect's choices in your Solution Exploration. If you discover a serious problem with a baked decision, raise it via `afx send architect` rather than overriding it in the spec.
|
|
37
|
+
|
|
38
|
+
If two baked decisions contradict each other (e.g., two different language choices), do not pick one — pause, flag the contradiction via `afx send`, and wait for resolution before drafting.
|
|
39
|
+
|
|
34
40
|
### 1. Clarifying Questions (ONLY IF NO SPEC EXISTS)
|
|
35
41
|
|
|
36
42
|
Before writing anything, ask clarifying questions to understand:
|
|
@@ -41,6 +41,10 @@ Use SPIR instead when:
|
|
|
41
41
|
- The work is **high-risk** — security-sensitive, user-facing, or broadly impactful
|
|
42
42
|
- You want to **review and adjust** the plan before implementation starts
|
|
43
43
|
|
|
44
|
+
## Baked Decisions (Optional)
|
|
45
|
+
|
|
46
|
+
When filing an issue for ASPIR, you can pin architectural decisions you don't want the builder or CMAP reviewers to re-litigate. Include a `## Baked Decisions` section (any heading level is fine) anywhere in the issue body. Useful categories: language, framework, deployment shape, key dependencies, decisions deferred to a later spec. The builder will copy the section verbatim into the spec's Constraints and treat each item as fixed; CMAP reviewers will not propose alternatives unless the spec itself fails to honor a stated decision. Leave the section out for issues where you want the builder to explore freely — absence is the no-op default. You can amend or rescind a baked decision at any time by updating the issue and respawning, or by sending the builder a direct instruction via `afx send`.
|
|
47
|
+
|
|
44
48
|
## Protocol Phases
|
|
45
49
|
|
|
46
50
|
ASPIR follows the same four phases as SPIR. For full phase documentation, see the [SPIR protocol](../spir/protocol.md).
|
|
@@ -1,38 +1,54 @@
|
|
|
1
|
-
# Implementation Review Prompt
|
|
1
|
+
# Implementation Review Prompt (BUGFIX)
|
|
2
2
|
|
|
3
3
|
## Context
|
|
4
|
-
You are reviewing
|
|
4
|
+
You are reviewing in-progress fix work for a **BUGFIX protocol** project. A builder has investigated a GitHub Issue, identified a root cause, and is implementing the fix + regression test. Your job is to verify the fix matches the issue's symptom and meets BUGFIX standards.
|
|
5
|
+
|
|
6
|
+
**BUGFIX is not SPIR.** There is **no spec, no plan, and no review document**. The GitHub Issue is the spec. The PR body will be the review. Do **not** request changes for missing `codev/specs/`, `codev/plans/`, or `codev/reviews/` artifacts.
|
|
5
7
|
|
|
6
8
|
## CRITICAL: Verify Before Flagging
|
|
7
9
|
|
|
8
10
|
Before requesting changes for missing configuration, incorrect patterns, or framework issues:
|
|
9
|
-
1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions
|
|
10
|
-
2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs
|
|
11
|
-
3. **Do not assume** your training data reflects the version in use — verify against project files
|
|
12
|
-
4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed
|
|
11
|
+
1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions.
|
|
12
|
+
2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs.
|
|
13
|
+
3. **Do not assume** your training data reflects the version in use — verify against project files.
|
|
14
|
+
4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed.
|
|
13
15
|
|
|
14
16
|
## Focus Areas
|
|
15
17
|
|
|
16
|
-
1. **
|
|
17
|
-
- Does the implementation
|
|
18
|
-
-
|
|
18
|
+
1. **Issue Adherence**
|
|
19
|
+
- Does the implementation actually resolve the symptom described in the GitHub Issue?
|
|
20
|
+
- Is the root cause fix targeted, or is it a workaround that masks the symptom?
|
|
21
|
+
|
|
22
|
+
2. **Regression Test**
|
|
23
|
+
- Is there a regression test that exercises the exact scenario from the issue?
|
|
24
|
+
- Without the fix applied, would this test fail? (The whole point.)
|
|
25
|
+
- Is the test deterministic?
|
|
26
|
+
- If no test was added, has the builder justified why (e.g., docs-only change with no testable behavior)?
|
|
27
|
+
|
|
28
|
+
3. **Scope Discipline**
|
|
29
|
+
- Is the change focused on the root cause only — no unrelated refactors, no drive-by fixes?
|
|
30
|
+
- Is the net diff staying under ~300 LOC? If it has grown larger, should this escalate to SPIR/TICK?
|
|
19
31
|
|
|
20
|
-
|
|
32
|
+
4. **Code Quality**
|
|
21
33
|
- Is the code readable and maintainable?
|
|
22
|
-
- Are there obvious bugs or issues?
|
|
23
|
-
- Are error cases handled appropriately?
|
|
34
|
+
- Are there obvious bugs or issues introduced by the fix?
|
|
35
|
+
- Are error cases handled appropriately for the path that was changed?
|
|
36
|
+
- No debug code, stray `console.log`, or commented-out code.
|
|
24
37
|
|
|
25
|
-
|
|
26
|
-
-
|
|
27
|
-
-
|
|
38
|
+
5. **Test Status**
|
|
39
|
+
- Existing tests still pass.
|
|
40
|
+
- Build still passes.
|
|
41
|
+
- No new flaky tests introduced.
|
|
28
42
|
|
|
29
|
-
|
|
30
|
-
- Does the implementation follow the plan?
|
|
31
|
-
- Are there plan items skipped or partially completed?
|
|
43
|
+
## Out of Scope (Do NOT request changes for)
|
|
32
44
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
45
|
+
The following are **not** part of the BUGFIX protocol and must **not** be cited as REQUEST_CHANGES reasons:
|
|
46
|
+
|
|
47
|
+
- Missing `codev/specs/<N>-*.md`, `codev/plans/<N>-*.md`, or `codev/reviews/<N>-*.md` — BUGFIX produces none of these. The GitHub Issue is the spec; the PR body is the review.
|
|
48
|
+
- Commit format `[Spec NNNN][Phase]` — BUGFIX uses `Fix #N: ...` or `[Bugfix #N] ...`. This is the protocol-mandated format, **not** a bug.
|
|
49
|
+
- `status.yaml` fields such as `build_complete: false` — porch manages `status.yaml`; the builder is **forbidden** from editing it manually. Treat porch state as informational, not a fixable issue.
|
|
50
|
+
- "Plan Alignment" or "Spec Adherence" — there is no plan and no spec to align with.
|
|
51
|
+
- Phase-scoping concerns — BUGFIX is single-phase by design. There are no plan phases to scope against.
|
|
36
52
|
|
|
37
53
|
## Verdict Format
|
|
38
54
|
|
|
@@ -51,22 +67,13 @@ KEY_ISSUES:
|
|
|
51
67
|
```
|
|
52
68
|
|
|
53
69
|
**Verdict meanings:**
|
|
54
|
-
- `APPROVE`:
|
|
55
|
-
- `REQUEST_CHANGES`:
|
|
56
|
-
- `COMMENT`: Minor suggestions
|
|
57
|
-
|
|
58
|
-
## Scoping (Multi-Phase Plans)
|
|
59
|
-
|
|
60
|
-
When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl):
|
|
61
|
-
- **ONLY review work belonging to the current plan phase**
|
|
62
|
-
- The query will specify which phase you are reviewing
|
|
63
|
-
- Do NOT request changes for functionality scheduled in later phases
|
|
64
|
-
- Do NOT flag missing features that are out of scope for this phase
|
|
65
|
-
- If unsure whether something belongs to this phase, check the plan file
|
|
70
|
+
- `APPROVE`: Fix and regression test are in good shape; builder can proceed to PR creation.
|
|
71
|
+
- `REQUEST_CHANGES`: Real BUGFIX-relevant issues (fix doesn't resolve the symptom, missing regression test without justification, scope creep, broken existing tests, etc.).
|
|
72
|
+
- `COMMENT`: Minor suggestions; builder can proceed but should consider the feedback.
|
|
66
73
|
|
|
67
74
|
## Notes
|
|
68
75
|
|
|
69
|
-
- This is
|
|
70
|
-
- Focus on "does this
|
|
71
|
-
- If referencing line numbers, use `file:line` format
|
|
72
|
-
- The builder needs actionable feedback to continue
|
|
76
|
+
- This is an implementation-level review, not the final PR review.
|
|
77
|
+
- Focus on "does this fix actually resolve the issue, and is it protected by a regression test" — not on artifacts from other protocols.
|
|
78
|
+
- If referencing line numbers, use `file:line` format.
|
|
79
|
+
- The builder needs actionable, protocol-correct feedback to continue.
|
|
@@ -1,36 +1,59 @@
|
|
|
1
|
-
# PR Ready Review Prompt
|
|
1
|
+
# PR Ready Review Prompt (BUGFIX)
|
|
2
2
|
|
|
3
3
|
## Context
|
|
4
|
-
You are performing a final self-check during the
|
|
4
|
+
You are performing a final self-check during the PR phase of the **BUGFIX protocol**. The builder has investigated a GitHub Issue, implemented a focused fix, and added a regression test. They are about to create — or have just created — a PR for the architect's integration review.
|
|
5
|
+
|
|
6
|
+
**BUGFIX is not SPIR.** Do **not** review against the SPIR three-document trinity. The artifacts of a BUGFIX project are:
|
|
7
|
+
- The originating **GitHub Issue** (serves as the spec)
|
|
8
|
+
- The **code fix** (minimal, focused on root cause)
|
|
9
|
+
- A **regression test** that fails without the fix and passes with it
|
|
10
|
+
- The **PR body** (Summary, Root Cause, Fix, Test Plan)
|
|
11
|
+
|
|
12
|
+
There is **no `codev/specs/`, `codev/plans/`, or `codev/reviews/` file** for a BUGFIX, and there should not be one. The commit format is `Fix #NNNN: <description>` (or `[Bugfix #NNNN] ...`), **not** `[Spec NNNN][Phase]`.
|
|
5
13
|
|
|
6
14
|
## Focus Areas
|
|
7
15
|
|
|
8
|
-
1. **
|
|
9
|
-
-
|
|
10
|
-
-
|
|
11
|
-
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
-
|
|
16
|
-
- Is test
|
|
17
|
-
-
|
|
18
|
-
|
|
19
|
-
3. **
|
|
20
|
-
- Is
|
|
21
|
-
-
|
|
22
|
-
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
-
|
|
27
|
-
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
-
|
|
32
|
-
-
|
|
33
|
-
|
|
16
|
+
1. **Issue Resolution**
|
|
17
|
+
- Does the fix actually resolve the symptom described in the issue?
|
|
18
|
+
- Does the PR body include `Fixes #<N>` so the issue auto-closes on merge?
|
|
19
|
+
- Does the PR description cover: Summary, Root Cause, Fix, Test Plan?
|
|
20
|
+
|
|
21
|
+
2. **Regression Test**
|
|
22
|
+
- Is there a regression test that targets the exact scenario from the issue?
|
|
23
|
+
- Would the test fail without the fix? (If reviewers can't tell, ask the builder to demonstrate.)
|
|
24
|
+
- Is the test deterministic (not flaky)?
|
|
25
|
+
- If the fix is documentation-only or otherwise truly untestable, has the builder explicitly justified the absence of a test?
|
|
26
|
+
|
|
27
|
+
3. **Scope Discipline**
|
|
28
|
+
- Is the change focused on the root cause? No unrelated refactors, no drive-by fixes for other bugs.
|
|
29
|
+
- Is the net diff under ~300 LOC (additions + deletions, excluding generated/lockfiles)?
|
|
30
|
+
- If the scope grew beyond a bugfix, should the builder have escalated to SPIR/TICK instead?
|
|
31
|
+
|
|
32
|
+
4. **Code Cleanliness**
|
|
33
|
+
- No debug code, `console.log`, or commented-out blocks left behind.
|
|
34
|
+
- No stray TODOs introduced by this fix.
|
|
35
|
+
- Code follows existing project conventions.
|
|
36
|
+
|
|
37
|
+
5. **Test Status**
|
|
38
|
+
- All existing tests pass.
|
|
39
|
+
- Build passes.
|
|
40
|
+
- No new flaky tests introduced.
|
|
41
|
+
|
|
42
|
+
6. **PR Hygiene**
|
|
43
|
+
- Commits use the BUGFIX format: `Fix #<N>: ...` or `[Bugfix #<N>] ...` (**not** `[Spec NNNN][Phase]`).
|
|
44
|
+
- Branch is up to date with main (or close enough for clean merge).
|
|
45
|
+
- PR is linked to the issue.
|
|
46
|
+
|
|
47
|
+
## Out of Scope (Do NOT request changes for)
|
|
48
|
+
|
|
49
|
+
The following are **not** part of the BUGFIX protocol and must **not** be cited as REQUEST_CHANGES reasons:
|
|
50
|
+
|
|
51
|
+
- Missing `codev/specs/<N>-*.md` — BUGFIX has no spec; the GitHub Issue is the spec.
|
|
52
|
+
- Missing `codev/plans/<N>-*.md` — BUGFIX has no plan.
|
|
53
|
+
- Missing `codev/reviews/<N>-*.md` — BUGFIX has no review document; review lives in the PR body.
|
|
54
|
+
- Commit format `[Spec NNNN][Phase]` — BUGFIX intentionally uses `Fix #N:` / `[Bugfix #N]`.
|
|
55
|
+
- `status.yaml` fields like `build_complete: false` — porch manages `status.yaml`; the builder is **forbidden** from editing it directly. Treat porch state as informational, not a fixable issue.
|
|
56
|
+
- Phase-scoping concerns — BUGFIX is a single-phase protocol; there are no plan phases to scope against.
|
|
34
57
|
|
|
35
58
|
## Verdict Format
|
|
36
59
|
|
|
@@ -49,24 +72,26 @@ KEY_ISSUES:
|
|
|
49
72
|
|
|
50
73
|
PR_SUMMARY: |
|
|
51
74
|
## Summary
|
|
52
|
-
[2
|
|
75
|
+
Fixes #<N>. [1-2 sentences on what was fixed.]
|
|
76
|
+
|
|
77
|
+
## Root Cause
|
|
78
|
+
[Brief explanation of what caused the bug]
|
|
53
79
|
|
|
54
|
-
##
|
|
55
|
-
|
|
56
|
-
- [Change 2]
|
|
80
|
+
## Fix
|
|
81
|
+
[Brief explanation of the fix]
|
|
57
82
|
|
|
58
83
|
## Test Plan
|
|
59
|
-
- [
|
|
84
|
+
- [Regression test description]
|
|
85
|
+
- [Manual verification, if applicable]
|
|
60
86
|
```
|
|
61
87
|
|
|
62
88
|
**Verdict meanings:**
|
|
63
|
-
- `APPROVE`:
|
|
64
|
-
- `REQUEST_CHANGES`:
|
|
65
|
-
- `COMMENT`: Minor items, can
|
|
89
|
+
- `APPROVE`: Bug is resolved, regression test is in place, PR is ready for architect review.
|
|
90
|
+
- `REQUEST_CHANGES`: Real BUGFIX-relevant issues to fix (missing regression test, fix doesn't resolve the symptom, scope creep, etc.).
|
|
91
|
+
- `COMMENT`: Minor items, can proceed but note feedback.
|
|
66
92
|
|
|
67
93
|
## Notes
|
|
68
94
|
|
|
69
|
-
- This is the builder's final self-review before hand-off
|
|
70
|
-
- The PR_SUMMARY
|
|
71
|
-
- Focus on "is this
|
|
72
|
-
- Any issues found here are cheaper to fix than during integration review
|
|
95
|
+
- This is the builder's final self-review before hand-off to the architect.
|
|
96
|
+
- The `PR_SUMMARY` block can be used directly as the PR description.
|
|
97
|
+
- Focus on "is this bug actually fixed and protected by a test" — not on artifacts from other protocols.
|
|
@@ -30,6 +30,12 @@ You are running in STRICT mode. This means:
|
|
|
30
30
|
Follow the SPIR protocol: `codev/protocols/spir/protocol.md`
|
|
31
31
|
Read and internalize the protocol before starting any work.
|
|
32
32
|
|
|
33
|
+
## Baked Decisions
|
|
34
|
+
|
|
35
|
+
If the issue body contains a section named "Baked Decisions" (any heading level, case-insensitive), treat its contents as fixed architectural decisions baked in by the architect. Do not autonomously override them in your spec, plan, or implementation. If you discover a serious reason to question a baked decision, surface that concern to the architect via `afx send` rather than relitigating it inside the spec/plan/review.
|
|
36
|
+
|
|
37
|
+
If the architect's baked-decisions section contains internal contradictions (e.g., two different language choices), do not pick one — pause, flag the contradiction to the architect via `afx send`, and wait for resolution before proceeding.
|
|
38
|
+
|
|
33
39
|
{{#if spec}}
|
|
34
40
|
## Spec
|
|
35
41
|
Read the specification at: `{{spec.path}}`
|
|
@@ -53,13 +59,23 @@ Follow the implementation plan at: `{{plan.path}}`
|
|
|
53
59
|
{{task_text}}
|
|
54
60
|
{{/if}}
|
|
55
61
|
|
|
56
|
-
##
|
|
62
|
+
## PR Strategy
|
|
63
|
+
|
|
64
|
+
**Do not autonomously open a PR per implementation phase.** Plan phases ship as git commits within a single PR, not as separate PRs. The plan's instruction that "each phase commits independently" refers to git commits, not PRs.
|
|
65
|
+
|
|
66
|
+
By default, the PR is opened during/after the final implement phase, with all phase-commits already on the branch.
|
|
67
|
+
|
|
68
|
+
### Architect-requested PRs
|
|
69
|
+
|
|
70
|
+
The architect MAY request a PR at any point — for spec review, mid-implementation feedback, slicing a large spec into shippable PRs, etc. When the architect explicitly asks for a PR earlier (or for additional PRs), follow that direction. The prohibition is specifically on the *builder* autonomously deciding to open per-phase PRs without architect request.
|
|
71
|
+
|
|
72
|
+
### Multi-PR Mechanics (when the architect requests sequential PRs)
|
|
57
73
|
|
|
58
|
-
Your worktree is persistent — it survives across PR merges.
|
|
74
|
+
Your worktree is persistent — it survives across PR merges. When the architect asks for sequential PRs (e.g., to slice a large spec into shippable pieces), use this loop:
|
|
59
75
|
|
|
60
76
|
1. Cut a branch, open a PR, wait for merge
|
|
61
77
|
2. After merge: `git fetch origin main && git checkout -b <next-branch> origin/main`
|
|
62
|
-
3. Continue to the next
|
|
78
|
+
3. Continue to the next slice, open another PR
|
|
63
79
|
4. Repeat
|
|
64
80
|
|
|
65
81
|
**Important**: Do NOT run `git checkout main` — git worktrees cannot check out a branch that's checked out elsewhere. Always branch off `origin/main` via fetch.
|
|
@@ -3,6 +3,12 @@
|
|
|
3
3
|
## Context
|
|
4
4
|
You are reviewing an implementation plan during the Plan phase. The spec has been approved - now you must evaluate whether the plan adequately describes HOW to implement it.
|
|
5
5
|
|
|
6
|
+
## Baked Decisions
|
|
7
|
+
|
|
8
|
+
If the issue body or the approved spec's Constraints section includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed (this extends the existing "don't re-litigate spec decisions" rule with explicit baked-decision language). Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns; reserve `REQUEST_CHANGES` for the case where the plan **fails to honor** a stated baked decision — that is a real defect.
|
|
9
|
+
|
|
10
|
+
If the baked decisions themselves contain contradictions, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding.
|
|
11
|
+
|
|
6
12
|
## Focus Areas
|
|
7
13
|
|
|
8
14
|
1. **Spec Coverage**
|
|
@@ -3,6 +3,12 @@
|
|
|
3
3
|
## Context
|
|
4
4
|
You are reviewing a feature specification during the Specify phase. Your role is to ensure the spec is complete, correct, and feasible before it moves to human approval.
|
|
5
5
|
|
|
6
|
+
## Baked Decisions
|
|
7
|
+
|
|
8
|
+
If the issue body or the spec's Constraints section includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns about a baked decision (the architect decides whether to rescind it); reserve `REQUEST_CHANGES` for the case where the spec **fails to honor** a stated baked decision — that is a real defect.
|
|
9
|
+
|
|
10
|
+
If the baked decisions themselves contain contradictions (e.g., two different language choices), do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding.
|
|
11
|
+
|
|
6
12
|
## Focus Areas
|
|
7
13
|
|
|
8
14
|
1. **Completeness**
|
|
@@ -31,6 +31,12 @@ ls codev/specs/{{project_id}}-*.md
|
|
|
31
31
|
|
|
32
32
|
**If no spec exists:** Proceed to Step 1 below.
|
|
33
33
|
|
|
34
|
+
### 0.5 Baked Decisions
|
|
35
|
+
|
|
36
|
+
Before exploring solution approaches, check the issue body for a section named "Baked Decisions" (any heading level, case-insensitive). If present, copy its content verbatim into the spec's Constraints section and treat each item as fixed. Do not autonomously relitigate the architect's choices in your Solution Exploration. If you discover a serious problem with a baked decision, raise it via `afx send architect` rather than overriding it in the spec.
|
|
37
|
+
|
|
38
|
+
If two baked decisions contradict each other (e.g., two different language choices), do not pick one — pause, flag the contradiction via `afx send`, and wait for resolution before drafting.
|
|
39
|
+
|
|
34
40
|
### 1. Clarifying Questions (ONLY IF NO SPEC EXISTS)
|
|
35
41
|
|
|
36
42
|
Before writing anything, ask clarifying questions to understand:
|
|
@@ -79,6 +79,10 @@ Each phase follows a build-verify loop: build the artifact, then verify with 3-w
|
|
|
79
79
|
- Dependency updates
|
|
80
80
|
- Emergency hotfixes (but do a lightweight retrospective after)
|
|
81
81
|
|
|
82
|
+
## Baked Decisions (Optional)
|
|
83
|
+
|
|
84
|
+
When filing an issue for SPIR, you can pin architectural decisions you don't want the builder or CMAP reviewers to re-litigate. Include a `## Baked Decisions` section (any heading level is fine) anywhere in the issue body. Useful categories: language, framework, deployment shape, key dependencies, decisions deferred to a later spec. The builder will copy the section verbatim into the spec's Constraints and treat each item as fixed; CMAP reviewers will not propose alternatives unless the spec itself fails to honor a stated decision. Leave the section out for issues where you want the builder to explore freely — absence is the no-op default. You can amend or rescind a baked decision at any time by updating the issue and respawning, or by sending the builder a direct instruction via `afx send`.
|
|
85
|
+
|
|
82
86
|
## Protocol Phases
|
|
83
87
|
|
|
84
88
|
### S - Specify (Collaborative Design Exploration)
|