adhoc-implement

Category: Development & Coding | Uploader: Clyra-AI | Downloads: 0 | Version: v1.0（Latest）
Implement a user-specified Gait backlog plan end-to-end with strict branch bootstrap, story-by-story execution, required test-matrix wiring, CodeQL validation, and final DoD/acceptance revalidation.
Changelog: Source: GitHub https://github.com/Clyra-AI/gait
Directory Structure

Current level: .agents/skills/adhoc-implement/
📁 agents/
- 📄 openai.yaml 248 B
📄 SKILL.md 7.8 KB
SKILL.md

---
name: adhoc-implement
description: Implement a user-specified Gait backlog plan end-to-end with strict branch bootstrap, story-by-story execution, required test-matrix wiring, CodeQL validation, and final DoD/acceptance revalidation.
disable-model-invocation: true
---

# Adhoc Plan Implementation (Gait)

Execute this workflow for: "implement this plan file", "run plan from <path>", or "execute backlog from a custom plan doc."

## Scope

- Repository: `/Users/tr/gait`
- Mandatory input argument: `plan_path`
- `plan_path` must point to a specific plan document provided by the user
- No default fallback to `product/PLAN_NEXT.md`
- Planning input only; this skill performs implementation work in repo

## Input Contract (Mandatory)

- Required: `plan_path`
- Accepted forms:
- absolute path
- repo-relative path
- Input must resolve to an existing readable file
- If `plan_path` is missing or invalid, stop with blocker report

## Preconditions

- Plan file includes required structure:
- `Global Decisions (Locked)`
- `Exit Criteria`
- `Test Matrix Wiring`
- Story sections with `Tasks`, `Repo paths`, `Run commands`, `Test requirements`, `Matrix wiring`, `Acceptance criteria`
- If structure is incomplete, stop and report missing sections

## Git Bootstrap Contract (Mandatory)

Run in order before implementation:

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

Rules:
- If worktree is dirty before step 1, 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

## Workflow

1. Parse plan and build execution queue by dependency and priority (`P0 -> P1 -> P2`).
   - Respect any explicit `Wave 1` before `Wave 2` sequencing in the plan.
2. Run baseline before first edit:
- `make lint-fast`
- `make test-fast`
- Record failures as pre-existing vs introduced.
3. Implement one story at a time (no parallel story execution).
4. For each story:
- implement scoped code/docs/tests only
- keep orchestration thin when architecture is touched; 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
- run story `Run commands`
- run story `Test requirements`
- run story `Matrix wiring` lanes
- mark complete only when acceptance criteria pass
5. Run epic-level validation after epic completion.
6. Run plan-level validation:
- `make prepush-full` (preferred), or
- `make prepush` plus `make codeql`
- Never finish without CodeQL unless explicitly waived by the user.
7. Revalidate all implemented work against:
- story acceptance criteria
- plan Definition of Done
- plan Exit Criteria
- Output `met/not met` with command evidence for each item.

## Command Contract (JSON Required)

When collecting evidence or emitting machine-readable status, use `gait` commands with `--json`, for example:

- `gait doctor --json`
- `gait gate eval --policy examples/policy/strict.yaml --intent examples/policy/intents/file_delete.json --json`

## Contract Discipline Rules

- If a story changes public CLI/SDK/schema surfaces, update 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
- fixture/golden updates
- compatibility or migration tests
- `make test-contracts`

2. CLI behavior changes (flags/JSON/exits):
- `cmd/gait/*_test.go` command coverage
- `--json` stability checks
- exit-code contract checks

3. Gate/policy/fail-closed changes:
- deterministic allow/block/require_approval fixtures
- fail-closed undecidable-path tests
- reason-code stability checks

4. Determinism/hash/sign/pack changes:
- byte-stability repeat-run tests
- canonicalization/digest stability checks
- verify/diff determinism tests
- `make test-packspec-tck` when applicable

5. Job runtime/state/concurrency changes:
- lifecycle tests (submit/checkpoint/pause/resume/cancel)
- atomic write/crash safety tests
- contention/concurrency tests
- chaos lanes when scoped

6. SDK/adapter boundary changes:
- wrapper behavior/error-mapping tests
- adapter conformance/parity tests
- `make test-adapter-parity` when applicable

7. Voice/context 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 flow changes

## Test Matrix Wiring (Enforcement)

Every 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: preserve Linux/macOS/Windows behavior on touched surfaces
- Risk lane: determinism/safety/security/perf suites as required

No story is complete if any required lane is skipped or failing.

## Surgical Docs Sync Rule

If a story changes user-visible behavior, 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 internal-only behavior with no user-visible impact, avoid unnecessary doc churn.

## Safety Rules

- Preserve determinism, offline-first defaults, fail-closed enforcement, schema stability, and exit-code stability.
- Never weaken non-allow => non-execute behavior.
- No destructive git operations unless explicitly requested.
- No silent skips of required tests/checks.
- Keep changes tightly scoped to active story.

## Quality Rules

- Claims must be evidence-backed by executed commands/tests.
- Do not claim tests ran if they were not run.
- Tests must use temp dirs for generated artifacts; do not leak test outputs into tracked source paths.
- If docs/CLI drift occurs due to user-visible changes, 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 blocked story immediately.
2. Report exact blocker and affected 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.
- Required story tests and matrix lanes pass.
- Plan Definition of Done is satisfied.
- Plan Exit Criteria is satisfied.
- CodeQL validation is green.

## Expected Output

- Execution summary: completed/deferred/blocked stories
- Change log: key files per story
- Validation log: commands and pass/fail
- Revalidation report: acceptance criteria + DoD + exit criteria (`met/not met` with evidence)
- Residual risk: remaining gaps and next required actions
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
adhoc-implement

Directory Structure

SKILL.md

Report

Notice
