Claude Cursor opencode Skill

phase-contract

Internal contract: the single owner of the eight phase-lint rules, the fixed PASS/BLOCKED result, and the normalized phase fingerprint. Consumed by plan-feature-scaffold, plan-fix, and execute-phase. Not a menu entry.

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download gtrabanco-agentic-workflow-skills_phase-contract-88248cc.zip · 3 KB

Install

skills CLI npx skills add https://github.com/gtrabanco/agentic-workflow/tree/main/skills/phase-contract
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install gtrabanco-agentic-workflow@llmmart
Git git clone https://github.com/gtrabanco/agentic-workflow.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole gtrabanco/agentic-workflow collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Phase Contract (internal)

The one authoritative owner of phase shape for this workflow. Planners lint every phase they emit against the eight rules below; execute-phase re-checks the same rules before any edit. Nothing else may define what a valid phase is — including which grammar a phase is written in.

When to use

  • The lane's plan step — lint every phase before emission.
  • execute-phase — phase-lint pre-flight guard before editing a phase.
  • Templates store the contract version + fingerprint + lint result, never the eight rules (they point here).

The eight phase-lint rules

Every implementation phase must pass all 8 boxes before it is emitted (planner skills) or executed (execute-phase pre-flight). Fail-closed: any unticked box blocks emission/execution until the phase is re-cut or split.

  1. Title names ONE deliverable — FAIL if it joins nouns with +, ,, &, and/y, or /. Sole authorized exception: the templates' literal closing title Hardening & PR (docs/features/_TEMPLATE/SPEC.md, docs/fix/_TEMPLATE/SPEC.md) is kept verbatim — its & is a normalization separator, not a deliverable joiner, and its title-deliverable normalizes to hardening-pr. Any other &-joined title still FAILs.
  2. One declared layer — each phase declares exactly one of the fixed enum schema/db | domain | api | ui | config/infra | docs | hardening | close-out; FAIL if any task's target file belongs to another. Tests for the phase's own layer belong to the phase; a test-only phase declares hardening.
  3. ≥ 1 task, ≤ 8 tasks — every phase carries at least one checkbox task; a phase with zero tasks is BLOCKED (fail-closed). Final hardening/close-out phase: 1–10, only the literal close-out chain.
  4. One checkbox = one deliverable — FAIL if a task contains a → chain of implementation steps, enumerates > 3 cases/scenarios, or creates > 1 file of distinct concerns.
  5. Zero decision words — FAIL on Decide, choose, OR between alternatives, If … then <change scope>.
  6. No conditional scope mutation — a task may not move work between phases at runtime.
  7. No external/manual gates inside implementation phases — human/out-of-repo verifications live in the hardening/close-out phase, marked manual.
  8. Machine-checkable done-when — every phase ends with one verifiable invariant (a command + expected outcome).

The executed-phase exemption (boxes 3 and 7 only). A fully-ticked phase is historical: those two boxes are positional — box 3's budget and box 7's gh pr placement both key off the plan's last phase — and a replan appends its work after an executed hardening (replan-findings' PHASE_APPEND.md), which would otherwise retro-block work that already passed this gate when it was emitted. The exemption is scoped to those two boxes: boxes 1, 2, 4, 5, 6 and 8 stay armed for an executed phase, and for an unemitted phase every box stays armed, so pre-ticking a phase to dodge a check is a defect, never a pass.

The two grammars (fix #272)

One contract, two shapes. scripts/phase-lint.mjs mechanizes exactly this split and never carries a second copy of the semantics:

grammar where shape
plan a plan file, or any ##/###/#### P<n> — <Title> heading heading + Layer: <enum> + - [ ] tasks + Done-when:
unit doc the unit doc's ## Tasks section one P<n> — <task> (validator: <command> <outcome>) bullet per phase, optionally carrying the executed-phase tick mark (- [x] P<n> — …; the tick is state, never a second phase), wrapped lines joining the bullet, plus an optional nested - Relevant files: <path, path…> line

Precedence is fail-closed and one-way: if a document carries any plan-style phase heading, the plan grammar governs it; only when it carries none does the unit-doc grammar apply; a document with no phase in either answers BLOCKED: no-phases. A P<n> bullet outside ## Tasks (a progress-log line, for instance) is prose, never a phase.

Mapping the eight boxes to a bullet phase

A bullet has no separate title line and declares no layer, so two boxes have no input and are skipped (not "passed"); the rest run unchanged over the bullet's joined text:

box unit-doc status
1 title names one deliverable n/a — there is no title line; the bullet is the task, and box 4 carries atomicity
2 one declared layer n/a — a unit doc declares no layer (layers belong to plans)
3 ≥ 1 task, ≤ 8 tasks applies — a bullet is exactly one task; a repeated P<n> number FAILs as duplicate unit-doc phase P<n>
4 one deliverable applies — same arrow-chain, >3-case and created-file checks
5 zero decision words applies, unchanged
6 no conditional scope mutation applies, unchanged
7 no external/manual gates applies with the final-bullet exemption: the last bullet is the unit doc's verification/close-out line, so manual / ask the user / gh pr are allowed there only
8 machine-checkable done-when applies — the bullet's (validator: …) span is the done-when: it must carry a backticked command and an expected outcome; a bullet without the span FAILs as bullet carries no \(validator: …)``

The Relevant files: sub-section is metadata

A nested - Relevant files: <path, path…> line under a bullet declares that phase's read set (the lane's plan step writes it from its own discovery). It is never a task: it does not count toward box 3, never feeds a box-2 target and is scanned by no rule. Every entry must be a path or a glob; an empty list, an empty entry or a token that is neither fails the phase closed under its own relevant-files: finding id — a malformed read set is reported, never dropped. Never-authority (same rule as every selector): a file that is not listed is never out of scope — an executor may always add one, logging it in the unit doc's Progress log.

Result — fixed PASS/BLOCKED output

Phase-lint: PASS (8/8)

A unit-doc bullet phase reports the boxes it actually runs:

P<n> Phase-lint: PASS (6/6) · fingerprint P<n>:unit-doc:<n-tasks>:<title-deliverable>

or, on the first failing box:

Phase-lint: BLOCKED — box <n>: <one-line reason>

A malformed Relevant files: sub-section reports under its own id:

P<n> relevant-files: <one-line reason>

A BLOCKED phase is re-cut or split; it is never emitted, committed, or executed as-is (no --force bypass exists for a non-atomic phase — that decision belongs to the user).

Normalized phase fingerprint

Each phase's fingerprint is a deterministic string over the phase's shape: P<n>:<layer>:<n-tasks>:<title-deliverable>. It binds the lint result to the exact phase version a plan committed to — templates and plans record Phase-lint: PASS (8/8) · fingerprint <fingerprint> so later re-lints and execute-phase can confirm nothing in the phase shape drifted since planning. A unit-doc bullet phase has no layer, so its slot is the literal unit-doc (P<n>:unit-doc:<n-tasks>:<title-deliverable>, title = the bullet text up to its first :, with the (validator: …) span removed); both grammars hash the same way, so a re-lint of either is comparable with its own earlier run.

Guardrails

  • Sole owner of the eight rules — planners and executor point here, never carry their own copy.
  • Never relax a rule to let a phase pass; re-cut the phase instead.
  • Docs only — no code, no branch.
Files (agentic-workflow)
  • SKILL.md 7.9 KB
    ---
    name: phase-contract
    user-invocable: false
    version: 4.10.0
    author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
    license: MIT
    description: >
      Internal contract: the single owner of the eight phase-lint rules, the two
      accepted phase grammars, the fixed PASS/BLOCKED result, and the normalized
      phase fingerprint. Consumed by `execute-phase` and the lane's `plan` step.
      Not a menu entry.
    ---
    
    # Phase Contract (internal)
    
    The one authoritative owner of phase shape for this workflow. Planners lint
    every phase they emit against the eight rules below; `execute-phase` re-checks
    the same rules before any edit. Nothing else may define what a valid phase is —
    including which grammar a phase is written in.
    
    ## When to use
    
    - The lane's `plan` step — lint every phase before emission.
    - `execute-phase` — phase-lint pre-flight guard before editing a phase.
    - Templates store the contract version + fingerprint + lint result, never the
      eight rules (they point here).
    
    ## The eight phase-lint rules
    
    Every implementation phase must pass all 8 boxes before it is emitted (planner
    skills) or executed (`execute-phase` pre-flight). Fail-closed: any unticked box
    blocks emission/execution until the phase is re-cut or split.
    
    1. **Title names ONE deliverable** — FAIL if it joins nouns with `+`, `,`, `&`,
       `and`/`y`, or `/`. Sole authorized exception: the templates' literal closing
       title `Hardening & PR` (`docs/features/_TEMPLATE/SPEC.md`,
       `docs/fix/_TEMPLATE/SPEC.md`) is kept verbatim — its `&` is a *normalization
       separator*, not a deliverable joiner, and its title-deliverable normalizes to
       `hardening-pr`. Any other `&`-joined title still FAILs.
    2. **One declared layer** — each phase declares exactly one of the fixed enum
       `schema/db | domain | api | ui | config/infra | docs | hardening | close-out`;
       FAIL if any task's target file belongs to another. Tests for the phase's own
       layer belong to the phase; a test-only phase declares `hardening`.
    3. **≥ 1 task, ≤ 8 tasks** — every phase carries at least one checkbox task; a phase with zero tasks is BLOCKED (fail-closed). Final hardening/close-out phase: 1–10, only the literal close-out chain.
    4. **One checkbox = one deliverable** — FAIL if a task contains a `→` chain of
       implementation steps, enumerates > 3 cases/scenarios, or creates > 1 file of
       distinct concerns.
    5. **Zero decision words** — FAIL on `Decide`, `choose`, `OR` between
       alternatives, `If … then <change scope>`.
    6. **No conditional scope mutation** — a task may not move work between phases
       at runtime.
    7. **No external/manual gates inside implementation phases** —
       human/out-of-repo verifications live in the hardening/close-out phase,
       marked `manual`.
    8. **Machine-checkable done-when** — every phase ends with one verifiable
       invariant (a command + expected outcome).
    
    **The executed-phase exemption (boxes 3 and 7 only).** A fully-ticked phase is historical:
    those two boxes are positional — box 3's budget and box 7's `gh pr`
    placement both key off the plan's last phase — and a replan appends its work
    *after* an executed hardening (`replan-findings`' `PHASE_APPEND.md`), which would
    otherwise retro-block work that already passed this gate when it was emitted.
    The exemption is scoped to those two boxes: boxes 1, 2, 4, 5, 6 and 8 stay armed for an
    executed phase, and for an unemitted phase every box stays armed, so pre-ticking
    a phase to dodge a check is a defect, never a pass.
    
    ## The two grammars (fix #272)
    
    One contract, two shapes. `scripts/phase-lint.mjs` mechanizes exactly this
    split and never carries a second copy of the semantics:
    
    | grammar | where | shape |
    |---|---|---|
    | **plan** | a plan file, or any `##/###/#### P<n> — <Title>` heading | heading + `Layer: <enum>` + `- [ ]` tasks + `Done-when:` |
    | **unit doc** | the unit doc's `## Tasks` section | one `P<n> — <task> (validator: <command> <outcome>)` bullet per phase, optionally carrying the executed-phase tick mark (`- [x] P<n> — …`; the tick is state, never a second phase), wrapped lines joining the bullet, plus an optional nested `- Relevant files: <path, path…>` line |
    
    Precedence is fail-closed and one-way: **if a document carries any plan-style
    phase heading, the plan grammar governs it**; only when it carries none does
    the unit-doc grammar apply; a document with no phase in either answers
    `BLOCKED: no-phases`. A `P<n>` bullet outside `## Tasks` (a progress-log line,
    for instance) is prose, never a phase.
    
    ### Mapping the eight boxes to a bullet phase
    
    A bullet has no separate title line and declares no layer, so two boxes have no
    input and are **skipped** (not "passed"); the rest run unchanged over the
    bullet's joined text:
    
    | box | unit-doc status |
    |---|---|
    | 1 title names one deliverable | **n/a** — there is no title line; the bullet is the task, and box 4 carries atomicity |
    | 2 one declared layer | **n/a** — a unit doc declares no layer (layers belong to plans) |
    | 3 ≥ 1 task, ≤ 8 tasks | applies — a bullet is exactly one task; a repeated `P<n>` number FAILs as `duplicate unit-doc phase P<n>` |
    | 4 one deliverable | applies — same arrow-chain, >3-case and created-file checks |
    | 5 zero decision words | applies, unchanged |
    | 6 no conditional scope mutation | applies, unchanged |
    | 7 no external/manual gates | applies with the **final-bullet exemption**: the last bullet is the unit doc's verification/close-out line, so `manual` / `ask the user` / `gh pr` are allowed there only |
    | 8 machine-checkable done-when | applies — the bullet's `(validator: …)` span **is** the done-when: it must carry a backticked command *and* an expected outcome; a bullet without the span FAILs as `bullet carries no \`(validator: …)\`` |
    
    ### The `Relevant files:` sub-section is metadata
    
    A nested `- Relevant files: <path, path…>` line under a bullet declares that
    phase's read set (the lane's plan step writes it from its own discovery). It is
    **never** a task: it does not count toward box 3, never feeds a box-2 target and
    is scanned by no rule. Every entry must be a path or a glob; an empty list, an
    empty entry or a token that is neither fails the phase closed under its own
    `relevant-files:` finding id — a malformed read set is reported, never dropped.
    **Never-authority (same rule as every selector):** a file that is *not* listed
    is never out of scope — an executor may always add one, logging it in the unit
    doc's Progress log.
    
    ## Result — fixed PASS/BLOCKED output
    
    ```text
    Phase-lint: PASS (8/8)
    ```
    
    A unit-doc bullet phase reports the boxes it actually runs:
    
    ```text
    P<n> Phase-lint: PASS (6/6) · fingerprint P<n>:unit-doc:<n-tasks>:<title-deliverable>
    ```
    
    or, on the first failing box:
    
    ```text
    Phase-lint: BLOCKED — box <n>: <one-line reason>
    ```
    
    A malformed `Relevant files:` sub-section reports under its own id:
    
    ```text
    P<n> relevant-files: <one-line reason>
    ```
    
    A BLOCKED phase is re-cut or split; it is never emitted, committed, or executed
    as-is (no `--force` bypass exists for a non-atomic phase — that decision belongs
    to the user).
    
    ## Normalized phase fingerprint
    
    Each phase's fingerprint is a deterministic string over the phase's shape:
    `P<n>:<layer>:<n-tasks>:<title-deliverable>`. It binds the lint result to the
    exact phase version a plan committed to — templates and plans record
    `Phase-lint: PASS (8/8) · fingerprint <fingerprint>` so later re-lints and
    `execute-phase` can confirm nothing in the phase shape drifted since planning.
    A unit-doc bullet phase has no layer, so its slot is the literal `unit-doc`
    (`P<n>:unit-doc:<n-tasks>:<title-deliverable>`, title = the bullet text up to
    its first `:`, with the `(validator: …)` span removed); both grammars hash the
    same way, so a re-lint of either is comparable with its own earlier run.
    
    ## Guardrails
    
    - Sole owner of the eight rules — planners and executor point here, never carry
      their own copy.
    - Never relax a rule to let a phase pass; re-cut the phase instead.
    - Docs only — no code, no branch.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.