Plan Implement

Plan Implementation (Gait)

Execute this workflow for: "implement the plan", "execute PLAN_NEXT", "ship plan stories", or "run backlog implementation end-to-end."

Scope

• Repository: /Users/tr/gait
• Default input plan: /Users/tr/gait/product/PLAN_NEXT.md
• Optional input plan: user-specified file under /Users/tr/gait/product/
• This skill executes code/docs/tests for planned stories.
• Out of scope by default:
• GitHub issue creation
• PR creation
• Automated comments/discussions
• Auto-commit/auto-push

Preconditions

• Plan file exists and is readable.
• Plan includes:
• Global Decisions (Locked)
• Exit Criteria
• Test Matrix Wiring
• Story-level Tasks, Repo paths, Run commands, Test requirements, Matrix wiring, Acceptance criteria
• If required sections are missing, stop and report blockers.

Git Bootstrap Contract (Mandatory)

Before implementation starts, run in order:

1. git fetch origin main
2. git checkout main
3. git pull --ff-only origin main
4. git checkout -b codex/<plan-scope>

Rules:

• If working tree is dirty before step 1, 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.

Workflow

1. Parse plan and build execution queue:

• Follow Minimum-Now Sequence first.
• Respect dependencies and P0 -> P1 -> P2.
• Respect any explicit Wave 1 before Wave 2 sequencing in the plan.

2. Run baseline before first code change:

• make lint-fast
• make test-fast
• Record failures as pre-existing vs introduced.

3. Execute one story at a time:

• Implement only scoped story changes.
• Keep orchestration thin when story scope touches architecture; move parsing, persistence, reporting, or policy logic into focused packages instead of coordinator layers.
• Make side effects explicit in API names/signatures and preserve symmetric semantics unless the distinction is intentionally named.
• Update tests required by story type.
• Update docs surgically only if user-facing behavior changed.
• Do not start next story until current story is validated.

4. Validate story completion:

• Run story Run commands.
• Run story Test requirements.
• Run story Matrix wiring lanes.
• If anything required is skipped, mark story incomplete.

5. Run epic-level validation after each epic:

• Execute relevant integration/acceptance suites for impacted surfaces.

6. Run final plan-level validation:

• make prepush-full (preferred, includes CodeQL), or
• make prepush and make codeql explicitly.
• Never finish without CodeQL unless user explicitly waives it.

7. Revalidate implementation against plan contracts:

• Re-check every implemented story against acceptance criteria.
• Re-check plan Definition of Done.
• Re-check plan Exit Criteria.
• Produce a met/not met checklist with command evidence for each item.

Command Anchors

• gait doctor --json to verify local environment and dependency readiness before implementation.
• gait gate eval --policy <policy.yaml> --intent <intent.json> --json for policy-story contract checks.
• gait pack verify <artifact.zip> --json for artifact-story integrity checks.

Contract Discipline Rules

• If a story changes public CLI/SDK/schema surfaces, update the stable/internal/deprecated surface notes in the same change.
• If versioning or schema compatibility behavior changes, document what is breaking vs additive and the migration expectation in the same story.
• If errors cross CLI or SDK boundaries, preserve structured machine-readable errors and stable mappings.
• If a story touches long-running workflows, verify cancellation and timeout propagation end-to-end.
• If enterprise customization pressure appears in scope, prefer explicit extension points over fork-only designs when feasible.
• For user-facing docs, explain integration hooks before internals and keep README.md, repo docs, and generated/public docs in sync.

Test Requirements by Work Type (Mandatory)

1. Schema/artifact contract changes:

• Schema validation tests
• Golden fixtures
• Compatibility/migration tests
• make test-contracts

2. CLI behavior changes (flags/JSON/exits):

• Command tests in cmd/gait/*_test.go
• JSON output stability tests
• Exit-code contract tests

3. Gate/policy/fail-closed changes:

• Deterministic allow/block/require_approval fixture tests
• Fail-closed undecidable-path tests
• Stable reason-code tests

4. Determinism/hash/sign/packaging changes:

• Repeat-run byte-stability tests
• Canonicalization/digest stability tests
• Verify/diff determinism checks
• make test-packspec-tck when relevant

5. Job runtime/state/concurrency changes:

• Lifecycle tests (submit/checkpoint/pause/resume/cancel)
• Atomic-write/crash-safety tests
• Contention/concurrency tests
• Chaos tests when scoped

6. SDK/adapter boundary changes:

• Wrapper behavior/error-mapping tests
• Adapter parity/conformance tests
• make test-adapter-parity when relevant

7. Voice/context evidence changes:

• make test-voice-acceptance and/or make test-context-conformance as applicable

8. Docs/examples changes:

• make test-docs-consistency
• make test-docs-storyline when operator flow changes

Test Matrix Wiring (Enforcement)

Each story must map to and run required lanes:

• Fast lane: make lint-fast, make test-fast
• Core lane: targeted unit/integration suites
• Acceptance lane: relevant make test-*-acceptance targets
• Cross-platform lane: ensure Linux/macOS/Windows-safe behavior for touched surfaces
• Risk lane: determinism/safety/security/perf suites as required by story

No story is complete without passing its mapped lanes.

Surgical Docs Sync Rule

If a story introduces user-visible behavior changes, update only impacted docs in the same story:

• /Users/tr/gait/README.md
• /Users/tr/gait/docs/
• /Users/tr/gait/docs-site/public/llms.txt
• /Users/tr/gait/docs-site/public/llm/*.md
• /Users/tr/gait/CONTRIBUTING.md
• /Users/tr/gait/CHANGELOG.md
• /Users/tr/gait/CODE_OF_CONDUCT.md
• /Users/tr/gait/SECURITY.md
• /Users/tr/gait/.github/ISSUE_TEMPLATE/
• /Users/tr/gait/.github/pull_request_template.md

If story is internal-only and behavior is unchanged, do not force doc churn.

Safety Rules

• Preserve non-negotiables: determinism, offline-first, fail-closed, schema stability, stable exit codes.
• Never weaken non-allow => non-execute paths.
• No destructive git operations unless explicitly requested.
• No auto-commit or auto-push.
• Keep changes story-scoped; no unrelated refactors.

Quality Rules

• Facts must be backed by command/test evidence.
• Do not claim tests ran if they did not.
• No silent skips of required checks.
• Tests must use temp output paths (no artifact leakage into source tree).
• If code/docs drift is introduced by user-facing change, patch docs in same story.
• Keep README first-screen coverage crisp: what it is, who it is for, how it integrates, and how to get value quickly.
• Keep one docs source of truth and update generated/public derivatives in the same story.

Blocker Handling

If blocked:

1. Stop the blocked story.
2. Report exact blocker and impacted acceptance criteria.
3. Continue only independent unblocked stories.
4. End with minimum unblock actions.

Completion Criteria

Implementation is complete only when all are true:

• All non-blocked in-scope stories are implemented.
• Story acceptance criteria are satisfied with evidence.
• Plan Definition of Done is satisfied.
• Plan Exit Criteria is satisfied.
• Required matrix lanes and CodeQL are passing.

Expected Output

• Execution summary: completed/deferred/blocked stories
• Change log: files modified per story
• Validation log: commands and pass/fail results
• Revalidation report: story acceptance + DoD + exit criteria (met/not met with evidence)
• Residual risk: remaining gaps and next required stories

Converted and distributed by TomeVault — claim your Tome and manage your conversions.