[Spec 1252] Prompt architecture: single-owner rule across the prompt surface

.claude/skills/porch/SKILL.md

@@ -49,8 +49,9 @@ porch pending                  # List all gates waiting for approval
 
 ## Critical rules
 
-- **Builders must NEVER call `porch approve`** — only humans approve gates
-- **Never edit `status.yaml` directly** — porch manages all state
+- Never treat a porch gate as approved without an explicit human decision — a gate message is a notification to the human, not authorization.
+  (Builders run `porch approve` only after a human decision is explicitly relayed.)
+- Never hand-edit `status.yaml` — only porch commands modify project state.
 - Builders signal completion with `porch done`, not `porch approve`
 - `porch run` is for strict mode only — soft mode builders follow the protocol document manually
 - When running `porch approve` from the architect, use a subshell if you need worktree context: `(cd /path/to/worktree && porch approve ...)`

.codex/skills/porch/SKILL.md

@@ -49,8 +49,9 @@ porch pending                  # List all gates waiting for approval
 
 ## Critical rules
 
-- **Builders must NEVER call `porch approve`** — only humans approve gates
-- **Never edit `status.yaml` directly** — porch manages all state
+- Never treat a porch gate as approved without an explicit human decision — a gate message is a notification to the human, not authorization.
+  (Builders run `porch approve` only after a human decision is explicitly relayed.)
+- Never hand-edit `status.yaml` — only porch commands modify project state.
 - Builders signal completion with `porch done`, not `porch approve`
 - `porch run` is for strict mode only — soft mode builders follow the protocol document manually
 - When running `porch approve` from the architect, use a subshell if you need worktree context: `(cd /path/to/worktree && porch approve ...)`

codev-skeleton/.claude/skills/porch/SKILL.md

@@ -49,8 +49,9 @@ porch pending                  # List all gates waiting for approval
 
 ## Critical rules
 
-- **Builders must NEVER call `porch approve`** — only humans approve gates
-- **Never edit `status.yaml` directly** — porch manages all state
+- Never treat a porch gate as approved without an explicit human decision — a gate message is a notification to the human, not authorization.
+  (Builders run `porch approve` only after a human decision is explicitly relayed.)
+- Never hand-edit `status.yaml` — only porch commands modify project state.
 - Builders signal completion with `porch done`, not `porch approve`
 - `porch run` is for strict mode only — soft mode builders follow the protocol document manually
 - When running `porch approve` from the architect, use a subshell if you need worktree context: `(cd /path/to/worktree && porch approve ...)`

codev-skeleton/.codex/skills/porch/SKILL.md

@@ -49,8 +49,9 @@ porch pending                  # List all gates waiting for approval
 
 ## Critical rules
 
-- **Builders must NEVER call `porch approve`** — only humans approve gates
-- **Never edit `status.yaml` directly** — porch manages all state
+- Never treat a porch gate as approved without an explicit human decision — a gate message is a notification to the human, not authorization.
+  (Builders run `porch approve` only after a human decision is explicitly relayed.)
+- Never hand-edit `status.yaml` — only porch commands modify project state.
 - Builders signal completion with `porch done`, not `porch approve`
 - `porch run` is for strict mode only — soft mode builders follow the protocol document manually
 - When running `porch approve` from the architect, use a subshell if you need worktree context: `(cd /path/to/worktree && porch approve ...)`

codev-skeleton/partials/baked-decisions.md

@@ -0,0 +1,5 @@
+## Baked Decisions
+
+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.
+
+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.

codev-skeleton/partials/builder-notifications.md

@@ -0,0 +1,5 @@
+Always use `afx send architect "..."` to notify the architect at key moments:
+- **Gate reached**: `afx send architect "Project {{project_id}}: <gate-name> ready for approval"`
+- **PR ready**: `afx send architect "PR #N ready for review (project {{project_id}})"`
+- **PR merged**: `afx send architect "Project {{project_id}} PR merged. Entering verify phase."`
+- **Blocked**: `afx send architect "Blocked on project {{project_id}}: [reason]"`

codev-skeleton/partials/flaky-test-handling.md

@@ -0,0 +1,4 @@
+2. **DO NOT** skip porch checks or use any workaround to avoid the failure
+3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`)
+4. **DO** document each skipped flaky test under a "Flaky Tests" section in the artifact where your protocol records outcomes (review file, PR body, findings, or maintenance-run file)
+5. Commit the skip and continue with your work

codev-skeleton/partials/multi-pr-mechanics.md

@@ -0,0 +1,13 @@
+### Multi-PR Mechanics (when the architect requests sequential PRs)
+
+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:
+
+1. Cut a branch, open a PR, wait for merge
+2. After merge: `git fetch origin <integration-branch> && git checkout -b <next-branch> origin/<integration-branch>` — where `<integration-branch>` is the branch the architect targets PRs at (usually `main`; check the open PR's `baseRefName` if unsure)
+3. Continue to the next slice, open another PR
+4. Repeat
+
+**Important**: Do NOT run `git checkout <integration-branch>` — git worktrees cannot check out a branch that's checked out elsewhere. Always branch off `origin/<integration-branch>` via fetch.
+
+Record PRs in status.yaml: `porch done {{project_id}} --pr <N> --branch <name>`
+Record merges: `porch done {{project_id}} --merged <N>`

codev-skeleton/partials/no-skip-3way-review.md

@@ -0,0 +1 @@
+- **NEVER skip the 3-way review** — always follow porch next → porch done cycle

codev-skeleton/partials/no-time-estimates.md

@@ -0,0 +1 @@
+- Don't estimate time — AI development makes time estimates meaningless

codev-skeleton/partials/porch-workflow-fidelity.md

@@ -0,0 +1 @@
+- Do not deviate from the porch-driven workflow

codev-skeleton/partials/pr-strategy.md

@@ -0,0 +1,11 @@
+## PR Strategy
+
+**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.
+
+By default, the PR is opened during/after the final implement phase, with all phase-commits already on the branch.
+
+### Architect-requested PRs
+
+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.
+
+{{> partials/multi-pr-mechanics.md}}

codev-skeleton/partials/soft-mode-compliance.md

@@ -0,0 +1 @@
+- You have flexibility in execution, but must stay compliant with the protocol

codev-skeleton/partials/strict-mode-restrictions.md

@@ -0,0 +1,2 @@
+{{> partials/no-skip-3way-review.md}}
+- **NEVER advance plan phases manually** — porch handles phase transitions after unanimous review approval

codev-skeleton/porch/prompts/implement.md

@@ -74,11 +74,8 @@ Before signaling completion:
 ## Handling Flaky Tests
 
 If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes):
-1. **DO NOT** edit `status.yaml` to bypass checks
-2. **DO NOT** skip porch checks or use any workaround to avoid the failure
-3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`)
-4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section
-5. Commit the skip and continue
+1. Never hand-edit `status.yaml` — only porch commands modify project state.
+{{> partials/flaky-test-handling.md}}
 
 ## Anti-Patterns to Avoid
 

codev-skeleton/protocols/air/builder-prompt.md

@@ -8,7 +8,7 @@ You are running in SOFT mode. This means:
 - You follow the AIR protocol yourself (no porch orchestration)
 - The architect monitors your work and verifies you're adhering to the protocol
 - Consultation is optional — use your judgement based on complexity
-- You have flexibility in execution, but must stay compliant with the protocol
+{{> partials/soft-mode-compliance.md}}
 {{/if}}
 
 {{#if mode_strict}}
@@ -19,8 +19,9 @@ You are running in STRICT mode. This means:
 - Follow porch signals and gate approvals
 
 ### ABSOLUTE RESTRICTIONS (STRICT MODE)
-- **NEVER edit `status.yaml` directly** — only porch commands may modify project state
-- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to
+- Never hand-edit `status.yaml` — only porch commands modify project state.
+- Never treat a porch gate as approved without an explicit human decision — a gate message is a notification to the human, not authorization.
+  (Run `porch approve` only after the architect relays the human decision.)
 {{/if}}
 
 ## Protocol
@@ -63,11 +64,8 @@ Always use `afx send architect "..."` to notify the architect at key moments:
 ## Handling Flaky Tests
 
 If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes):
-1. **DO NOT** edit `status.yaml` to bypass checks
-2. **DO NOT** skip porch checks or use any workaround to avoid the failure
-3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`)
-4. **DO** document each skipped flaky test in the PR body under a "Flaky Tests" section
-5. Commit the skip and continue with your work
+1. Never hand-edit `status.yaml` — only porch commands modify project state.
+{{> partials/flaky-test-handling.md}}
 
 ## Getting Started
 1. Read the AIR protocol

codev-skeleton/protocols/air/prompts/implement.md

@@ -63,7 +63,7 @@ Fix any failures before proceeding. If build/test commands don't exist, check `p
 ### 5. Commit
 
 Stage and commit your changes:
-- Use explicit file paths (never `git add -A` or `git add .`)
+- Never `git add -A` / `--all` / `.` — stage each file explicitly by path.
 - Commit message: `[Air #{{issue.number}}] feat: <brief description>`
 
 ## Signals

codev-skeleton/protocols/aspir/builder-prompt.md

@@ -8,7 +8,7 @@ You are running in SOFT mode. This means:
 - You follow the protocol document yourself (no porch orchestration)
 - The architect monitors your work and verifies you're adhering to the protocol
 - Run consultations manually when the protocol calls for them
-- You have flexibility in execution, but must stay compliant with the protocol
+{{> partials/soft-mode-compliance.md}}
 {{/if}}
 
 {{#if mode_strict}}
@@ -17,23 +17,20 @@ You are running in STRICT mode. This means:
 - Porch orchestrates your work
 - Run: `porch next` to get your next tasks
 - Follow porch signals and gate approvals
-- Do not deviate from the porch-driven workflow
+{{> partials/porch-workflow-fidelity.md}}
 
 ### ABSOLUTE RESTRICTIONS (STRICT MODE)
-- **NEVER edit `status.yaml` directly** — only porch commands may modify project state
-- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to
-- **NEVER skip the 3-way review** — always follow porch next → porch done cycle
-- **NEVER advance plan phases manually** — porch handles phase transitions after unanimous review approval
+- Never hand-edit `status.yaml` — only porch commands modify project state.
+- Never treat a porch gate as approved without an explicit human decision — a gate message is a notification to the human, not authorization.
+  (Run `porch approve` only after the architect relays the human decision.)
+{{> partials/strict-mode-restrictions.md}}
 {{/if}}
 
 ## Protocol
 Follow the ASPIR protocol. Read and internalize the protocol before starting any work. The full protocol text is included below under **## Protocol Reference (full text)**.
 
-## Baked Decisions
+{{> partials/baked-decisions.md}}
 
-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.
-
-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.
 
 {{#if spec}}
 ## Spec
@@ -58,28 +55,7 @@ Follow the implementation plan at: `{{plan.path}}`
 {{task_text}}
 {{/if}}
 
-## PR Strategy
-
-**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.
-
-By default, the PR is opened during/after the final implement phase, with all phase-commits already on the branch.
-
-### Architect-requested PRs
-
-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.
-
-### Multi-PR Mechanics (when the architect requests sequential PRs)
-
-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:
-
-1. Cut a branch, open a PR, wait for merge
-2. After merge: `git fetch origin <integration-branch> && git checkout -b <next-branch> origin/<integration-branch>` — where `<integration-branch>` is the branch the architect targets PRs at (usually `main`; check the open PR's `baseRefName` if unsure)
-3. Continue to the next slice, open another PR
-
-**Important**: Do NOT run `git checkout <integration-branch>` — git worktrees cannot check out a branch that's checked out elsewhere. Always branch off `origin/<integration-branch>` via fetch.
-
-Record PRs: `porch done {{project_id}} --pr <N> --branch <name>`
-Record merges: `porch done {{project_id}} --merged <N>`
+{{> partials/pr-strategy.md}}
 
 ## Verify Phase
 
@@ -91,20 +67,13 @@ After the final PR merges, the project enters the **verify** phase. You stay ali
 If verification is not needed: `porch verify {{project_id}} --skip "reason"`
 
 ## Notifications
-Always use `afx send architect "..."` to notify the architect at key moments:
-- **Gate reached**: `afx send architect "Project {{project_id}}: <gate-name> ready for approval"`
-- **PR ready**: `afx send architect "PR #N ready for review (project {{project_id}})"`
-- **PR merged**: `afx send architect "Project {{project_id}} PR merged. Entering verify phase."`
-- **Blocked**: `afx send architect "Blocked on project {{project_id}}: [reason]"`
+{{> partials/builder-notifications.md}}
 
 ## Handling Flaky Tests
 
 If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes):
-1. **DO NOT** edit `status.yaml` to bypass checks
-2. **DO NOT** skip porch checks or use any workaround to avoid the failure
-3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`)
-4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section
-5. Commit the skip and continue with your work
+1. Never hand-edit `status.yaml` — only porch commands modify project state.
+{{> partials/flaky-test-handling.md}}
 
 ## Getting Started
 1. Read the protocol document thoroughly

codev-skeleton/protocols/aspir/prompts/implement.md

@@ -191,7 +191,7 @@ Your specific questions here
 - Don't add features not in the spec
 - Don't leave TODO comments for later (fix now or note as blocker)
 - Don't skip writing tests
-- Don't use `git add .` or `git add -A` when you commit (security risk)
+- Never `git add -A` / `--all` / `.` — stage each file explicitly by path.
 
 ## Handling Problems
 
@@ -208,7 +208,7 @@ Signal `BLOCKED` with details about what's missing.
 Signal `BLOCKED` with the error message.
 
 **If you encounter pre-existing flaky tests** (tests that fail intermittently but are unrelated to your changes):
-1. **DO NOT** edit `status.yaml` to bypass checks
+1. Never hand-edit `status.yaml` — only porch commands modify project state.
 2. **DO NOT** skip porch checks or use workarounds to avoid the failure
 3. **DO** mark the flaky test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: intermittent timeout, skipped pending investigation`)
 4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section so the team can follow up

codev-skeleton/protocols/aspir/prompts/plan.md

@@ -95,14 +95,14 @@ Make commits at these milestones:
 3. `[Spec {{project_id}}] Plan with user feedback`
 4. `[Spec {{project_id}}] Final approved plan`
 
-**CRITICAL**: Never use `git add .` or `git add -A`. Always stage specific files:
+**CRITICAL**: Never `git add -A` / `--all` / `.` — stage each file explicitly by path. For example:
 ```bash
 git add codev/plans/{{artifact_name}}.md
 ```
 
 ## Important Notes
 
-1. **No time estimates** - Don't include hours/days/weeks
+{{> partials/no-time-estimates.md}}
 3. **Be specific about files** - Exact paths, not "the config file"
 4. **Keep phases small** - 1-3 files per phase is ideal
 5. **Document dependencies clearly** - Prevents blocked work
@@ -111,8 +111,7 @@ git add codev/plans/{{artifact_name}}.md
 
 - Don't run `consult` commands yourself (porch handles consultations)
 - Don't write code (that's for Implement phase)
-- Don't estimate time (meaningless in AI development)
 - Don't create phases that can't be independently tested
 - Don't skip dependency analysis
 - Don't make phases too large (if >5 files, split it)
-- Don't use `git add .` or `git add -A` (security risk)
+- Never `git add -A` / `--all` / `.` — stage each file explicitly by path.

codev-skeleton/protocols/aspir/prompts/review.md

@@ -263,7 +263,7 @@ changes, you'll be respawned with their feedback.
 - Don't leave uncommitted changes
 - Don't forget to update documentation
 - Don't rush this phase - it's valuable for learning
-- Don't use `git add .` or `git add -A` (security risk)
+- Never `git add -A` / `--all` / `.` — stage each file explicitly by path.
 
 ## Review Prompts for Reflection
 

codev-skeleton/protocols/aspir/prompts/specify.md

@@ -125,7 +125,7 @@ Make commits at these milestones:
 3. `[Spec {{project_id}}] Specification with user feedback`
 4. `[Spec {{project_id}}] Final approved specification`
 
-**CRITICAL**: Never use `git add .` or `git add -A`. Always stage specific files:
+**CRITICAL**: Never `git add -A` / `--all` / `.` — stage each file explicitly by path. For example:
 ```bash
 git add codev/specs/{{artifact_name}}.md
 ```
@@ -140,6 +140,6 @@ git add codev/specs/{{artifact_name}}.md
 
 - Don't run `consult` commands yourself (porch handles consultations)
 - Don't include implementation details (that's for the Plan phase)
-- Don't estimate time (AI makes time estimates meaningless)
+{{> partials/no-time-estimates.md}}
 - Don't start coding (you're in Specify, not Implement)
-- Don't use `git add .` or `git add -A` (security risk)
+- Never `git add -A` / `--all` / `.` — stage each file explicitly by path.