gnd-workflow 0.1.0

package/templates/workflow/skills/gnd-chart/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: "gnd-chart"
+description: "Structured plan format for manual planning and navigator-led execution. Use when charting multi-step plans intended for @gnd-navigator to dispatch as legs via runSubagent in any project."
+user-invocable: true
+disable-model-invocation: true
+contracts:
+  - navigator-gates-unconfirmed
+---
+# Chart
+
+Plan multi-step work as structured legs for `@gnd-navigator` to dispatch to `gnd-diver`.
+
+## Workflow Role
+
+Break the user's goal into bounded, reviewable legs. Project constraints come from project guidance sources, not hidden assumptions.
+
+## Project Context Resolution
+
+Identify authoritative guidance in priority order:
+
+1. User request and attachments
+2. Workspace instructions
+3. `README.md` and area docs
+4. Skills, file instructions, or agent files referenced by those docs
+5. Build, test, packaging, deployment, or CI config
+
+Read only what matters. Record useful sources in the plan's `## Project Context`.
+
+---
+
+## Workflow
+
+```text
+Discovery → Alignment → Draft → Workshop → Refinement
+```
+
+### Phase 1 — Discovery
+
+Explore the codebase: read relevant files, run searches, identify affected modules. Skim archived plans or critiques for prior corrections if they exist. Do not write legs yet.
+
+### Phase 2 — Alignment
+
+One round after Discovery. Summarize findings, then ask scope/approach questions. At minimum: (a) in-scope vs out-of-scope, (b) non-obvious tradeoffs, (c) genuine ambiguities. Skip only when the task maps to a single unambiguous leg.
+
+### Phase 3 — Draft
+
+Present a **plan outline** — not full legs:
+
+- Plan title
+- Leg list: ID, label, one-line intent
+- Proposed dispatch order
+
+### Phase 4 — Workshop
+
+After the draft, automatically workshop each leg:
+
+1. Present legs one at a time (group tightly coupled ones at your discretion).
+2. For each leg, show in chat:
+   - Title, ID
+   - **Goal link** — one sentence connecting this leg to the user's overall goal
+   - 2–3 bullets of key intent
+   - Owned files
+   - One alternative or tradeoff if applicable; otherwise state "mechanical"
+3. Ask the user. Options: **Approve as-is** (recommended), concrete alternatives from the summary, **Remove**. Freeform always available.
+4. Apply feedback immediately. Move to next leg.
+5. Mark confirmed legs `Confirmed: yes`.
+
+Do not advance until all legs are confirmed or removed.
+
+### Phase 5 — Refinement
+
+**User Intent confirmation.** Present a 2–4 sentence summary of the user's goal distilled from the conversation. Ask: "Does this capture your goal?" Options: **Looks right** (recommended), **Needs revision**. Update and re-confirm if revised.
+
+Then write the full plan with all fields. Output only:
+1. Changes made during workshop
+2. Any unconfirmed legs
+3. Final dispatch order
+
+The plan file is the source of truth — do not paste the full plan into chat.
+
+---
+
+## Re-entry Triggers
+
+**"review"** or **"walk me through it"**: re-enter workshop for unconfirmed legs, or ask which confirmed leg to revisit. Confirmed legs are not re-presented unless a subsequent change significantly alters their scope.
+
+---
+
+## Plan File Location
+
+Plans live in `.planning/` as `active-plan-YYYY-MM-DD-HHmm-<slug>.md`.
+
+- View existing plans first; leave them in place.
+- Each plan gets its own timestamped file. Multiple live plans may coexist.
+- Only one plan should be actively dispatched at a time.
+- After implementation, leave the plan for critique. `gnd-critique` appends findings then archives.
+
+---
+
+## Plan Structure
+
+```markdown
+# Plan: [Short Title]
+
+## Project Context
+- Sources:
+  - `path/to/doc.md` - why it matters
+- Constraints:
+  - [Derived rules]
+- Full validation:
+  - `command` or checklist
+- Delivery verification:
+  - deployed URL, package check, artifact check, local-only, or `none`
+
+## User Intent
+[2-4 sentences confirmed by user during Refinement. Navigator and critique
+reference this to evaluate alignment.]
+
+## Legs
+
+### LEG-1: [Area] - [Short description]
+- Status: pending
+- Confirmed: yes | no
+- Goal link: [How this leg serves the User Intent]
+- Depends on: none | LEG-N
+- Owned files:
+  - `path/to/file.ts`
+- Read-only:
+  - `path/to/reference.ts` - reason
+- Deferred shared edits:
+  - `shared/file.ts` - what to change
+- Verification: `command`
+- Intent: [Detailed implementation description]
+
+## Dispatch Order
+Sequential via runSubagent (navigator reviews between each):
+1. LEG-1 (label) - no dependencies
+2. LEG-2 (label) - depends on LEG-1
+After all complete: deferred edits → full validation → delivery verification → commit → push.
+```
+
+---
+
+## Field Definitions
+
+| Field | Notes |
+|-------|-------|
+| **Status** | `pending`, `in-progress`, `done`, `failed`. Only navigator updates during dispatch. |
+| **Confirmed** | `yes`/`no`. Set to `yes` on user approval in workshop. Navigator won't dispatch `no`. |
+| **Depends on** | `none` or a leg ID. Dispatch Order makes the sequence explicit. |
+| **Dispatch agent** | Always `gnd-diver`. If a leg seems too vague, tighten the intent or split it — don't assign a different agent. |
+| **Owned files** | Exhaustive list the sub-agent may modify. No globs. One leg per file — never split. Grep during Draft/Workshop to confirm targets exist. |
+| **Read-only** | Reference files the sub-agent reads but must not modify. Include a reason. |
+| **Deferred shared edits** | Changes to shared files (`package.json`, routers, etc.) the navigator applies after all legs complete. Be precise. |
+| **Verification** | Single shell command covering only this leg's files. Not the project's full gate. For test legs: list explicit per-file expected assertions. |
+| **Intent** | The critical field. Must be **specific** (name functions, interfaces, selectors), **self-contained** (embed needed constraints), **outcome-oriented** (what code does when done), and **bounded** (number sub-tasks). |
+
+---
+
+## Scoping Guidelines
+
+- **One module or feature per leg** when files are tightly coupled. Don't split types and state that always change together.
+- **Split by independence** when modules don't share types.
+- **Maximize parallelism** — minimize serial dependency chains.
+- **≤15 owned files per leg.** Larger → find a seam to split on.
+- **Shared files** (`package.json`, `build.ts`, routers, shared styles) never appear in owned sets. Use deferred shared edits.
+
+---
+
+## Embedding Project Constraints
+
+Leg intents must embed relevant project constraints so sub-agents don't rediscover them. Common categories: performance/bundle budgets, layout checkpoints, accessibility, content/copy rules, state/persistence, styling/design-system, build/test/release, motion/audio/media. Include only what affects each leg.
+
+---
+
+## Dispatch Order Section
+
+List legs in dispatch order. Note dependencies and parallelism. End with:
+
+```markdown
+After all complete: deferred edits → `## Project Context` full-validation → delivery verification → commit → push.
+```
+
+Project-specific sync, packaging, or publish steps belong in `## Project Context`.

package/templates/workflow/skills/gnd-critique/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: "gnd-critique"
+description: "Evaluate completed work against intent and delivered behavior. Two modes: plan critique (evaluates an implemented live plan after @gnd-navigator execution) and field review (--field-review / --fr, triages runtime or workflow observations, implements fixes, and archives findings)."
+user-invocable: true
+disable-model-invocation: true
+---
+# Critique
+
+Evaluate delivered work against the plan. Validation and delivery checks come from the plan's `## Project Context`, workspace instructions, READMEs, and skills.
+
+Two modes — detect from invocation:
+
+| Flag | Mode | When |
+|------|------|------|
+| *(default)* | Plan critique | After a navigator-led plan is implemented and validated. Requires an implemented live plan. |
+| `--field-review` / `--fr` | Field review | Runtime, delivery, or workflow observations that don't map to a critique target. No target required. |
+
+---
+
+## Mode: Field Review
+
+User tests the delivered system and reports observations.
+
+### FR Phase 1 — Gather Context
+
+For process-only reviews (memory-path conflicts, workflow bugs), skip inapplicable delivery checks — read workflow files and `.planning/` state instead.
+
+1. **Determine evaluation surface.** Use the user's report plus `## Project Context`, workspace instructions, READMEs, and skills to decide: deployed web, local runtime, package/artifact, or pure workflow.
+2. **Verify delivery** when the evaluation surface (step 1) is deployed, published, or has a preview — check the live surface. If the surface is local-only, workflow-only, or has no delivery verification defined, mark not applicable.
+3. **Inspect real surface** when applicable via `fetch_webpage` or similar.
+4. **Read relevant code/process files** based on user observations. Enough to form hypotheses, not the whole codebase.
+5. **Check archived plans.** Skim `.planning/archive/` for recent plans touching affected areas.
+
+### FR Phase 2 — Triage
+
+Classify each observation:
+
+| Category | Meaning | Output |
+|----------|---------|--------|
+| **Bug** | Broken — visible defect, wrong behavior | Root cause hypothesis with file + line refs |
+| **UX issue** | Works but wrong feel — confusing, inconsistent | Description + what "right" looks like, with code evidence |
+| **Design question** | Not clearly a bug — questioning a decision | Restate original intent, note concern, flag for planning |
+| **Recurring** | Previously flagged in a prior critique/cycle | Link to prior finding, escalate priority |
+
+Per observation: what the user reported, category, evidence (code refs, surface observations, prior findings), hypothesis, severity (blocker/high/medium/low).
+
+### FR Phase 3 — Findings & Plan
+
+Present triaged findings, then propose an implementation plan:
+
+```text
+## Field Review: [Area]
+Date: [date]
+Delivery: [verified / mismatch / not applicable]
+
+### Findings
+#### 1. [Title]
+- Reported: [user's words]
+- Category: Bug / UX issue / Design question / Recurring
+- Severity: blocker / high / medium / low
+- Evidence: [refs]
+- Hypothesis: [root cause + fix location]
+
+### Implementation Plan
+Ordered fixes with files and approach. Design questions flagged for user decision.
+
+### Process Observations
+Process-level corrections if findings reveal a gap. Otherwise omit.
+```
+
+### FR Phase 4 — Implement
+
+Fix bugs and UX issues in severity order (blockers first). Design questions → present to user first. Run tests after each fix.
+
+### FR Phase 5 — Deploy & Verify
+
+1. Run full validation from `## Project Context` / workspace instructions / READMEs / skills.
+2. Commit and push (when in scope) with a descriptive message.
+3. Verify delivery yourself — don't ask the user to check first.
+4. Tell user any needed refresh/update step only if the surface requires it.
+5. User re-verifies. Persistent findings → another Phase 4 round.
+6. **Archive.** Create `.planning/archive/<YYYY-MM-DD>-field-review-<slug>.md` with findings + implementation + verification.
+7. Update process files if findings reveal a gap.
+
+---
+
+## Mode: Plan Critique
+
+After `@gnd-navigator` implements and validates a plan.
+
+```text
+Gather Context → Interactive Review → Analysis → Findings → Apply
+```
+
+### PC Phase 1 — Gather Context
+
+1. **Resolve critique target.** List `.planning/` (exclude `archive/`). Supports `active-plan-*.md`.
+   - Prefer a plan with `## Implementation` and no `## Critique`.
+   - User-selected plan takes priority.
+   - One candidate → select it. Multiple → ask.
+
+2. **Read implementation.** Use the commit SHA from `## Implementation` to review the change. Check the commit's file summary and targeted diffs.
+
+3. **Resolve validation context.** From `## Project Context`, or derive from workspace instructions, READMEs, skills, and CI config.
+
+4. **Verify delivery** if the project defines a delivery surface. Failed validation/delivery is a blocker.
+
+5. **Inspect real surface** when applicable.
+
+6. **Read process files.** Targeted reads of:
+   - `.agents/skills/gnd-chart/SKILL.md`
+   - `.agents/skills/gnd-critique/SKILL.md`
+   - `.agents/agents/gnd-navigator.agent.md`
+   - `.agents/agents/gnd-diver.agent.md`
+
+
+### PC Phase 2 — Interactive Review
+
+Three beats to surface gaps before automated analysis.
+
+**Beat 1 — Intent Check.** Show `## User Intent` from the plan. Ask: *"Does this still capture what you wanted?"* Options: **Yes** (recommended), **Needs adjustment**.
+- If confirmed → Beat 2.
+- If "yeah, but also X" → **chart gap** (workshop failed to capture this). Flag immediately as `gnd-chart` correction.
+- If substantial revision → update User Intent, re-evaluate legs.
+
+**Beat 2 — Leg Walkthrough.** One at a time (or grouped by area). Show what *actually shipped* from the diff, not the plan's intent. Ask: *"How did this land?"* Options: **Landed well**, **Has issues**, **Didn't notice it**.
+
+Anchor to plan scope. Off-topic observations → triage (below).
+
+**Beat 3 — Open Impressions.** *"Anything else you noticed?"* Triage all responses.
+
+**Off-topic triage:**
+
+| Signal | Class | Action |
+|--------|-------|--------|
+| Relates to User Intent but no leg covers it | Chart gap | Flag as `gnd-chart` correction |
+| Unrelated area plan didn't touch | Out of scope | Add to Field Review Holding List |
+| Ambiguous | Clarify | Ask user, then classify |
+
+### PC Phase 3 — Analysis
+
+Cross-reference plan, code, user observations, and triage to identify:
+
+1. **Intent-vs-implementation gaps** — scope creep, incomplete implementation, drift.
+2. **Delivered-behavior issues** — match bugs/UX gaps to specific legs. Root cause: bad plan, bad execution, or unforeseen interaction?
+3. **Chart gaps** — for each, identify which charting phase failed (Discovery/Alignment/Workshop) and why.
+4. **User effectiveness patterns** — vague prompt context, unstated scope. Collaborative observations to help tighten future chart-time input.
+5. **Process patterns** — recurring problems across legs, leg shapes that worked well or poorly, navigator review gaps.
+
+### PC Phase 4 — Findings
+
+Present structured findings before applying:
+
+```text
+## Critique Findings: [Plan Title]
+
+### What Worked
+- [Evidence-backed positives]
+
+### What Didn't
+- [Problems tied to specific legs or steps]
+
+### Chart Gaps
+- [Missing intent facets + which chart phase failed and why]
+
+### User Effectiveness
+- [Collaborative prompting observations]
+
+### Blockers
+- [Validation/delivery failures]
+
+### Corrections for Next Cycle
+- [Concrete, actionable changes — not vague aspirations]
+
+### Field Review Holding List
+- [Out-of-scope observations from Phase 2]
+
+### Process File Updates
+- [Each file + what changes]
+```
+
+Get user approval before applying.
+
+### PC Phase 5 — Apply
+
+1. **Append** `## Critique` section to the plan file.
+2. **Update process files** with approved changes. All files are eligible (`gnd-chart`, `gnd-critique`, `gnd-navigator`, `gnd-diver`, project-local files). Only where findings warrant it.
+3. **Archive** the plan → `.planning/archive/<YYYY-MM-DD>-<slug>.md`.
+4. **Report** what was updated and the archive path.
+5. **Field review handoff** if the holding list is non-empty.
+
+---
+
+## Key Rules
+
+- **Archive, don't delete.** Move the plan to archive after critique. Other live plans remain.
+- **Evidence over opinion.** Every finding references a specific leg, diff, or observation.
+- **Actionable corrections only.** "Be more specific" is not actionable. "Include viewport checkpoints for CSS layout legs" is.
+- **Don't over-correct.** If most legs executed cleanly, the process works. Focus on the gaps.
+- **Respect scope.** Plan critique evaluates what shipped. It doesn't redesign the product or start a new plan.