Skip to content

skills: resolve planning-to-implementation handoff coherence #76

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
davidahmann merged 1 commit into from
Feb 28, 2026
Merged

skills: resolve planning-to-implementation handoff coherence #76

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion .agents/skills/adhoc-implement/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,11 @@ Run in order before implementation:
4. `git checkout -b codex/adhoc-<plan-scope>`

Rules:
- If worktree is dirty before step 1, stop and report blocker
- If worktree is dirty before step 1:
- Allow only the plan-handoff case where all modified files are planning outputs and include `plan_path`.
- Planning-output allowlist: `./product/PLAN_NEXT.md`, `./product/PLAN_v1.0.md`, and selected `plan_path`.
- In the allowlist case, require current branch is already `main`, run step 1, skip steps 2-3, and run step 4 to branch with plan edits preserved.
- Otherwise stop and report blocker.
- If unexpected unrelated changes appear during execution, stop immediately and ask how to proceed
- Do not auto-commit or auto-push unless explicitly requested by the user

Expand Down
6 changes: 6 additions & 0 deletions .agents/skills/adhoc-plan/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,12 @@ Validation rules:
11. Verify quality gates.
12. Overwrite `output_plan_path` with the final plan.

## Handoff Contract (Planning -> Implementation)

- This skill intentionally leaves `output_plan_path` modified in the working tree.
- Expected follow-up is `adhoc-implement` with the same `plan_path` on a new branch.
- If additional dirty files exist beyond the generated plan file, stop and scope/clean before implementation.

## Command Contract (JSON Required)

Use `wrkr` commands with `--json` whenever the plan needs machine-readable evidence, for example:
Expand Down
6 changes: 5 additions & 1 deletion .agents/skills/backlog-implement/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,11 @@ Before implementation starts, run in order:
4. `git checkout -b codex/<plan-scope>`

Rules:
- If working tree is dirty before step 1, stop and report blocker for user decision.
- If working tree is dirty before step 1:
- Allow only the plan-handoff case where all modified files are planning outputs and include selected `plan_path`.
- Planning-output allowlist: `./product/PLAN_NEXT.md`, `./product/PLAN_v1.0.md`, and selected `plan_path`.
- In the allowlist case, require current branch is already `main`, run step 1, skip steps 2-3, and run step 4 to branch with plan edits preserved.
Copy link

@chatgpt-codex-connector chatgpt-codex-connector bot Feb 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Base handoff branches on updated main

In the plan-handoff path this rule skips step 3 and immediately runs git checkout -b, which means the new branch is created from whatever commit local main already has. git fetch does not advance the current branch by default (see git fetch -h, where --update-head-ok is an explicit opt-in), and git checkout -h states -b <branch> only “create and checkout a new branch.” If origin/main moved after the local checkout, implementation starts from a stale base and can miss upstream fixes or produce avoidable merge/test churn.

Useful? React with 👍 / 👎.

- Otherwise stop and report blocker for user decision.
- If unexpected changes appear during implementation, stop immediately and ask how to proceed.
- Do not switch to other branches unless user explicitly requests it.

Expand Down
9 changes: 8 additions & 1 deletion .agents/skills/backlog-plan/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,8 @@ Execute this workflow when asked to convert strategic feature recommendations in
- `./product/dev_guides.md`
- `./product/architecture_guides.md`
- Structure references (match level of detail and style):
- `gait/product/PLAN_v1.md` (reference only, if available in your environment)
- `./product/PLAN_v1.md` (preferred local reference, if available)
- `../gait/product/PLAN_v1.md` (fallback reference, if available in your environment)
- Output file: `./product/PLAN_NEXT.md` (unless user specifies a different target)
- Planning only. Do not implement code or docs outside the target plan file.

Expand Down Expand Up @@ -55,6 +56,12 @@ If these are missing, stop and output a gap note instead of inventing details.
12. Add definition of done and release/exit gate criteria.
13. Write full plan to target file, overwriting prior contents.

## Handoff Contract (Planning -> Implementation)

- This skill intentionally leaves the generated plan file modified in the working tree.
- Expected follow-up is `backlog-implement` using that plan file on a new branch.
- If additional dirty files exist beyond the plan output, stop and scope/clean before implementation.

## Non-Negotiables

- Preserve Wrkr core contracts: determinism, offline-first defaults, fail-closed policy posture, schema stability, and exit code stability.
Expand Down
11 changes: 9 additions & 2 deletions .agents/skills/initial-plan/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
name: initial-plan
description: Transform the Wrkr PRD in product/wrkr.md into a world-class, zero-ambiguity execution plan that mirrors the detail level of gait/product/PLAN_v1.md, while enforcing product/dev_guides.md and product/architecture_guides.md standards for coding, testing, CI, determinism, architecture governance, and contracts. Use when the user asks for an initial build plan from the PRD (not from ideas/recommendations).
description: Transform the Wrkr PRD in product/wrkr.md into a world-class, zero-ambiguity execution plan that mirrors the detail level of product/PLAN_v1.md (or gait/product/PLAN_v1.md when needed), while enforcing product/dev_guides.md and product/architecture_guides.md standards for coding, testing, CI, determinism, architecture governance, and contracts. Use when the user asks for an initial build plan from the PRD (not from ideas/recommendations).
disable-model-invocation: true
---

# PRD to Initial Execution Plan (Wrkr)
Expand Down Expand Up @@ -61,7 +62,7 @@ If these are missing, stop and output a gap note instead of inventing policy.
- frugal architecture/cost impact requirements
- chaos/hardening/perf lane triggers and failure-hypothesis expectations

4. Read `gait/product/PLAN_v1.md` to mirror structure depth and story-level specificity.
4. Read `./product/PLAN_v1.md` (or `../gait/product/PLAN_v1.md` if local reference is unavailable) to mirror structure depth and story-level specificity.

5. Inspect current repository baseline and convert observed reality into a `Current Baseline (Observed)` section:
- existing directories and key files
Expand Down Expand Up @@ -90,6 +91,12 @@ If these are missing, stop and output a gap note instead of inventing policy.

11. Write the plan to the target file, replacing prior contents.

## Handoff Contract (Planning -> Implementation)

- This skill intentionally leaves the generated plan file modified in the working tree.
- Expected follow-up is an implementation skill on a new branch with that plan as input.
- If additional dirty files exist beyond the generated plan file, stop and scope/clean before implementation.

## Non-Negotiables

- Preserve Wrkr core contracts: deterministic execution, zero data exfiltration by default, fail-closed policy posture, stable schema contracts, stable exit code contracts.
Expand Down