groundwork-method 0.0.1 → 0.10.0

package/src/hidden-skills/groundwork-scan/templates/architecture-findings.md

@@ -0,0 +1,42 @@
+# Architecture Findings
+
+> Consumed by `groundwork-architecture-extract`. Exact structural facts extracted from the codebase and the `repo-map.json` code map. The heaviest findings slice — the architecture phase reverse-engineers `docs/architecture/index.md`, domain stubs, and contract docs from it.
+
+## Service / Partition Map
+
+<!-- One row per service or partition: name, root path, language, runtime, responsibility, and — for partitions a consumer interacts with — the interface surface type (graphical-ui | cli | agentic-protocol); `—` for core services. Record every surface-bearing partition: the architecture extract writes the surface registry from this column, and a surface missing here is missing from the registry. -->
+
+| Service | Root | Language | Responsibility | Surface |
+|---|---|---|---|---|
+
+## Entry Points
+
+<!-- Per service: the process entry point(s) — main.go, the server bootstrap, the worker loop. -->
+
+## External Contracts
+
+<!-- Every machine-readable contract found, with its path: OpenAPI/Swagger specs, AsyncAPI schemas, Protobuf/gRPC definitions, GraphQL SDL. When a service exposes HTTP routes with NO formal spec, record that gap explicitly — it is a candidate gap-ledger entry. -->
+
+## Data Models & Persistence
+
+<!-- Entities from schemas, migrations, ORM models. The datastores in use (Postgres, Redis, etc.) and where each service's schema/migrations live. -->
+
+## Dependencies
+
+<!-- Internal: which service depends on which (from the code map). External: third-party services and SDKs each service calls (Stripe, Clerk, a message broker, an LLM provider). -->
+
+## Communication Patterns
+
+<!-- Sync (HTTP/gRPC) vs async (queue/stream/pubsub) edges between services, with the transport. -->
+
+## Infrastructure & Deployment
+
+<!-- docker-compose services and ports, IaC (Terraform/k8s/helm), CI workflows, env examples. Whether a system-test harness exists. -->
+
+## Notable Patterns
+
+<!-- Architectural patterns observed: hexagonal layering, transactional outbox, CQRS, repository pattern, etc. -->
+
+## Risks & TODOs
+
+<!-- TODO/FIXME markers of architectural weight, deprecated paths, obvious divergences from a clean service standard. Feeds the gap ledger. -->

package/src/hidden-skills/groundwork-scan/templates/design-findings.md

@@ -0,0 +1,23 @@
+# Design Findings
+
+> Consumed by `groundwork-design-system-extract`. Raw design signals extracted from config and code. Not a design system — the extract phase distils them and interviews to fill aesthetic-intent gaps.
+
+## Interface Surfaces
+
+<!-- One line per interface surface found: partition, type (graphical-ui | cli | agentic-protocol), platform evidence. Record every surface — a repo can carry a web app AND a CLI, and one omitted here is lost to the design and registry phases. A repo with one surface gets one line. -->
+
+## Design Tokens
+
+<!-- Colour, spacing, typography, radius, shadow values found in Tailwind config, CSS variables, theme files, or a tokens source. Quote concrete values with their source path. -->
+
+## Component Library
+
+<!-- UI component inventory: a design-system package, shadcn/MUI/Chakra, custom components. Where they live. -->
+
+## Theme & Framework
+
+<!-- UI framework, styling approach (Tailwind, CSS-in-JS, CSS modules), dark-mode handling, terminal theming for a CLI. -->
+
+## Interaction & Accessibility Signals
+
+<!-- Motion/animation conventions, focus handling, ARIA usage, keyboard support, reduced-motion handling — anything signalling interaction and accessibility posture. -->

package/src/hidden-skills/groundwork-scan/templates/overview.md

@@ -0,0 +1,26 @@
+# Scan Overview
+
+> Shared scan baseline. Read by every brownfield extract phase. Not a canonical doc — deleted at the end of setup.
+
+## Repository Shape
+
+<!-- single-service | multi-part | monorepo -->
+
+## Parts
+
+<!-- One row per part: id, root path, language, framework -->
+
+| Part | Root | Language | Framework |
+|---|---|---|---|
+
+## Partition Map
+
+<!-- One line per partition: id — one-sentence purpose -->
+
+## Scan Depth
+
+<!-- quick | deep | exhaustive -->
+
+## Coverage & Gaps
+
+<!-- What was read fully vs sampled. Name any directory only sampled at the chosen depth, and anything excluded that a downstream phase might need. Honest gaps here let the extract phases ask the user; silent omission reads as completeness. -->

package/src/hidden-skills/groundwork-scan/templates/product-findings.md

@@ -0,0 +1,23 @@
+# Product Findings
+
+> Consumed by `groundwork-product-brief-extract`. Raw signals about what the product does and for whom, extracted from code and docs. Not a brief — the extract phase distils and interviews to fill gaps.
+
+## Value Proposition
+
+<!-- What the README, landing copy, and package description claim the product is and does. -->
+
+## User-Facing Capabilities
+
+<!-- Features inferred from routes, pages, commands, public API surface. One bullet each, with the evidence path. -->
+
+## Product Surface
+
+<!-- The interaction medium(s) detected: web UI, CLI, API/protocol, mobile. -->
+
+## Inferred Users
+
+<!-- Who the product appears built for, inferred from copy, auth model, and feature shape. Mark as inference. -->
+
+## Licensing & Monetisation Signals
+
+<!-- LICENSE, pricing/billing integrations, tiers, paywalls — anything signalling the commercial model. -->

package/src/hidden-skills/groundwork-scan/templates/scan-state.json

@@ -0,0 +1,19 @@
+{
+  "status": "scanning",
+  "schema_version": 1,
+  "scan_depth": null,
+  "fan_out_mode": null,
+  "classification": {
+    "repo_shape": null,
+    "parts": []
+  },
+  "exclusions": ["node_modules", ".git", "dist", "build", "coverage", "vendor", "target", ".next", "*.min.js", "*.map", "lockfiles"],
+  "partitions": [],
+  "findings_files": [
+    "scan/overview.md",
+    "scan/product-findings.md",
+    "scan/design-findings.md",
+    "scan/architecture-findings.md"
+  ],
+  "resume_pointer": null
+}

package/src/hidden-skills/groundwork-stack-forge/instructions.md

@@ -0,0 +1,150 @@
+---
+name: groundwork-stack-forge
+description: >
+  Forge a first-class starting point when the architecture's chosen stack has no
+  GroundWork generator — a native desktop app (AppKit, WinUI), an embedded daemon, an
+  unsupported language or framework. Researches the stack, authors a self-contained
+  engineer skill for it, and builds a Day-2 seed wired into `./dev`, then hands the
+  Day-2 checklist to MVP planning. Invoked from the scaffold phase's unsupported-stack
+  branch so going off the paved road still lands the project in a good place.
+---
+
+# groundwork-stack-forge
+
+The paved road is the set of stacks GroundWork has a generator for. This skill is what
+happens when the architecture, deliberately, goes off it — a macOS-native app, a Rust
+service, an embedded firmware target, a language the generators do not produce. The wrong
+answer is a passive shrug: "no generator, you're on your own." The right answer — the one
+that makes GroundWork worth using off-script — is to do everything a generator would have
+done, by hand and to the same bar: a real engineering skill for the stack, and a seed that
+clears the Day-2 baseline.
+
+You are a staff engineer who has shipped in this stack and is setting up a teammate to
+succeed in it. Two artifacts come out of this: **an engineer skill** the project's agent
+loads on every task in this stack, and **a seed** — a small, real, running starting point
+that already does config validation, error handling, debugging, and the rest of the Day-2
+baseline in this stack's idiom. The seed is a skeleton, not a finished product; the first
+bets grow it. Both must be good enough that a senior practitioner in the stack would nod.
+
+Apply the `groundwork-writer` skill when producing any output document — the engineer
+skill, infrastructure notes, the hand-off. Declarative, assertive, zero-hedging.
+
+## Operating Contract
+
+**Load and apply all protocols from `.groundwork/skills/operating-contract.md`
+(contract v1).** This skill runs inside the scaffold phase, so the Phase Lifecycle, Living
+Documents, and Hand-off protocols bind it: what you forge is recorded in the canonical docs
+and carried to MVP, never left as undocumented local cleverness.
+
+The governing rule is the Day-2 baseline: read
+`docs/principles/delivery/day-2-operational-baseline.md` now. It is the bar the seed is held
+to and the source of the checklist you hand to MVP — its two rules (**no empty capabilities**,
+**off-script still lands well**) are why this skill exists.
+
+## When this runs
+
+The scaffold phase routes here from Phase 1 when it maps a service or surface to a stack no
+generator can produce and the user chooses to build it properly (rather than reverse the
+architecture onto a supported stack, or hand-roll it with no support). You inherit the
+chosen stack from `docs/architecture/index.md` and `docs/surfaces.md`; do not re-litigate the
+choice — the architecture made it. Your job is to honour it well.
+
+## The forge pipeline
+
+Run these in order. Each stage feeds the next; do not skip ahead.
+
+### Stage 1 — Frame the stack and classify the target
+
+Read the architecture and the surface registry for what was actually chosen: the language,
+the framework, the platform, and what this component *is* — a service, a daemon, a CLI, a
+native UI surface. Classify it, because the classification drives everything downstream: it
+picks the engineer-skill family (Backend or Surface — see
+`references/authoring-engineer-skills.md`), and it decides which Day-2 items apply in this
+idiom and which are genuinely N/A.
+
+State the frame back in two or three lines — "a native macOS menu-bar app in Swift/AppKit; a
+Surface-family target; no server, so the API and schema baseline items are N/A, but config,
+errors, debugging, logging, graceful teardown, a pure core, a test harness, and `./dev`
+integration all apply." Confirm it with the user before researching.
+
+### Stage 2 — Research the stack
+
+Invoke the `deep-research` skill to build a cited, current picture of how this stack is built
+*well*. Scope the research to the decisions the engineer skill and seed must get right:
+
+- The idiomatic project layout and the one golden-path way to structure a pure core behind a
+  thin shell in this stack.
+- The build / run / debug loop — how a developer attaches a debugger and reads logs (the
+  highest-leverage DX affordance).
+- The error model — how errors are typed, propagated, and surfaced.
+- Concurrency / event model, configuration, graceful teardown, and packaging.
+- The test harness that runs in seconds, and how it is driven headlessly (for `./dev` and the
+  system-test runner).
+- The plausible-but-wrong idioms — what a strong general model writes that a senior
+  practitioner would reject.
+
+Do not author from memory where the stack has moved; the research is what keeps the skill
+from being confidently out of date.
+
+### Stage 3 — Author the engineer skill
+
+Write `.agents/skills/groundwork-<stack>-engineer/` to the standard in
+`references/authoring-engineer-skills.md` — the right family, the section spine, self-contained
+references (no sync-anchor), the house style, and the **eval-before-accept loop**. Do not
+accept the skill until you have run it against two or three realistic first tasks and it comes
+out senior-grade against both the Day-2 baseline and stack idiom. Read the nearest shipped
+engineer skill in the project as a worked example of shape.
+
+### Stage 4 — Build the Day-2 seed by adopting the skill
+
+Now build the seed — and build it *as* the engineer skill you just wrote would have you build
+it. This dogfoods the skill: if it cannot guide a good seed, it is not done, so loop back to
+Stage 3. The seed is a skeleton that clears the **applicable** Day-2 baseline items in this
+stack's idiom — a pure core with a thin shell, config loaded and validated at startup, typed
+errors handled at the boundary, a debugging entry point, structured logs, graceful teardown,
+and a test that runs in seconds and proves the wired thing does something real. It is not a
+product; it is the smallest real thing that is already operable and debuggable.
+
+### Stage 5 — Wire the seed into `./dev` and the test loop
+
+A seed outside `./dev` is a side process, not a first-class citizen — exactly the failure the
+Day-2 baseline forbids. Wire it in:
+
+- **`./dev`** — register the seed so `./dev start` runs it. If it is a process `./dev` can
+  launch, register a runner in `.dev/dev.config.json` (name + launch command). If it needs a
+  build-then-run or a richer verb, add a project command under `.dev/commands/` (it appears in
+  `./dev help` and may shadow a built-in). Never leave `./dev start` with nothing to do for
+  this project.
+- **Surface registry** — if the target is a surface, register it in `docs/surfaces.md` and
+  `.groundwork/surfaces.json` with `scaffold: forged` and its `testMedium`; if it is a service,
+  record it in `docs/architecture/infrastructure.md` like any other managed unit.
+- **System tests** — give it a headless test medium the `system-test-runner` can drive
+  (the harness from Stage 2), so it joins the system test loop rather than sitting outside it.
+
+Then verify: `./dev start` brings the seed up, `./dev status` shows it, and its test runs
+green. Debug and fix anything that does not — a forged seed that does not boot is not done.
+
+### Stage 6 — Hand the Day-2 checklist to MVP
+
+The seed proves the shape; the first bets earn the depth. Walk the Day-2 baseline once for this
+stack and, for each item, record *satisfied by the seed*, *to be built by a bet*, or *N/A
+because…*. Write that list into the scaffold cache (`.groundwork/cache/scaffold-cache.md`) under
+a `## Forged Stack Checklist` heading — the scaffold commit folds it into the MVP hand-off, and
+MVP scopes the to-be-built items into the first bets. This is how "the checklist becomes part of
+the MVP."
+
+Record the forged stack in `docs/architecture/infrastructure.md` (its run command, its debug entry point, its
+test command) so the next developer runs it without asking, then return control to the scaffold
+phase to finish its mapping and commit.
+
+## Output Expectations
+
+- An engineer skill at `.agents/skills/groundwork-<stack>-engineer/` that passes its own
+  eval loop and reads like a senior practitioner wrote it — self-contained, no sync-anchor.
+- A seed that boots through `./dev start`, clears the applicable Day-2 baseline in the stack's
+  idiom, and has a test that runs green.
+- The seed registered in `./dev`, the surface/infra docs, and the system-test loop — a
+  first-class citizen, never a side process.
+- A Day-2 checklist in the scaffold hand-off so the first bets are scoped to finish the job.
+- No empty capabilities anywhere in what you forged — every command, endpoint, and test medium
+  you materialised does something real.

package/src/hidden-skills/groundwork-stack-forge/references/authoring-engineer-skills.md

@@ -0,0 +1,107 @@
+# Authoring an Engineer Skill (runtime standard)
+
+This reference is how the forge writes an engineer skill that holds up. It distils the
+two dev-time skills GroundWork builds with — `skill-writer` (how a skill should read) and
+`skill-creator` (how a skill is tested before it is trusted) — into a standard you apply
+inside a user's project, where neither of those skills is installed. Treat it as the bar:
+a forged engineer skill that does not meet it is not finished.
+
+## What you are building
+
+An engineer skill is a **persistent implementation expert for one stack**, delivered into
+the project at `.agents/skills/groundwork-<stack>-engineer/` so the team's agent loads it
+on every relevant task. It is not documentation about the stack — it is the senior
+engineer's judgement, written so an agent makes the calls a senior engineer would: where
+code goes, what to never do, how to verify, which idiom is right and which is plausible
+but wrong.
+
+It mirrors the three engineer skills GroundWork ships (`groundwork-go-engineer`,
+`groundwork-python-engineer`, `groundwork-nextjs-engineer`). Read the nearest one in the
+project (or, if scaffolding has not run, the closest sibling you can find) as a worked
+example before you write — match its shape, not its content.
+
+## Pick the family
+
+Engineer skills come in two shapes. Choose by what the engineer is wired into, then keep
+that family's section order so a reader predicts the skill's internals.
+
+| Family | Use for | Section spine |
+|---|---|---|
+| **Backend** | services, daemons, CLIs, anything gated by specs and sibling components | Operating Contract → Required First Checks → Context Routing → Skill Handoffs → Execution Checklist → Safety Gates → Quick Reference → Output Expectations |
+| **Surface** | desktop, mobile, native UI, anything whose failure mode is plausible-but-wrong UI idiom | Operating Contract → Core Pillars → How to Use This Skill → Task Routing → Safety Gates → Hallucination Controls → Output Expectations → Antipatterns |
+
+A native macOS AppKit app is **Surface**. A Rust HTTP service is **Backend**. A headless
+sync daemon is **Backend**. When a target straddles both (a desktop app with a real local
+backend), pick by the larger risk and fold the other family's concerns into a section.
+
+## The anatomy
+
+```
+groundwork-<stack>-engineer/
+├── SKILL.md          # the spine above; frontmatter name + a pushy description
+└── references/       # 8–14 files, each a decision-time lens on one area
+```
+
+- **`SKILL.md`** carries the spine, kept tight — it routes to references, it does not inline
+  them. The frontmatter `description` must be *pushy*: it decides whether the agent loads
+  the skill at all, so name the stack and the trigger work explicitly.
+- **`references/`** are written for that stack's decision points — its project layout, its
+  error model, its concurrency/event model, its build/debug loop, its test harness, its
+  idiomatic libraries, its packaging. Each file is a lens an engineer reaches for mid-task,
+  not a tutorial.
+- **No `sync-anchor.md`.** The shipped engineer skills pin GroundWork's in-repo principle
+  files by hash; a forged skill lives in a user project with no such source to pin, so it is
+  **self-contained** — its references stand on their own. Do not fabricate a sync-anchor.
+
+## How it must read (the house style)
+
+These are the `skill-writer` rules. They are why the shipped skills work; hold to them.
+
+- **Write intent, not scripts.** Never quote phrases for the agent to repeat. "Verify the
+  build is green before opening a slice," not a canned sentence to print.
+- **Explain why each rule exists.** A constraint with its reason is adopted; one imposed is
+  worked around. "Keep view state out of the model layer — it makes the model untestable and
+  ties redraws to business logic," not "don't put state in the model."
+- **No hedging.** Drop "should," "typically," "you might want to." State the call or cut it.
+- **Lead with the belief, not the rejection.** Say what the right idiom is and why, before
+  what to avoid.
+- **Calibrate with examples, not adjectives.** Show a shallow handling next to the deep one.
+  Agents match examples; they cannot match "be idiomatic."
+- **Front-load the mental model.** Open the skill with the stack's shape — its core
+  abstraction, its golden path — so every later rule lands against a frame.
+- **Expert peer stance.** The skill proposes and explains; it does not bark orders.
+
+## Earn the skill before you trust it (the eval loop)
+
+This is the `skill-creator` discipline, adapted for runtime: a skill you wrote and never
+tested is a draft, not an expert. Before you accept a forged engineer skill, prove it.
+
+1. **Draft** the SKILL.md and references against the family and the house style.
+2. **Pose 2–3 realistic tasks** the skill will face — the first real bets for this stack
+   (e.g. "add a window that lists records from the local store," "handle a failed network
+   call without crashing the UI"). These are the test, kept small for speed; do not overfit
+   the skill to them.
+3. **Run each task against the skill** — actually reason through how an agent loaded with the
+   skill would do it. Judge the output against two yardsticks: the **Day-2 baseline**
+   (`docs/principles/delivery/day-2-operational-baseline.md` — config, errors, debugging,
+   observability, shutdown, pure core, tests, `./dev`) and **stack idiom** (would a senior
+   practitioner in this stack recognise it as right, not just compiling?).
+4. **Find the gaps and generalise.** Where the skill let the task drift shallow or off-idiom,
+   fix the skill — but fix the *general* rule, not the specific case, since the skill runs on
+   tasks you did not test.
+5. **Re-run and repeat** until the tasks come out senior-grade and the user agrees the skill
+   reads like an expert. Then accept it.
+
+## What "good" looks like
+
+A forged engineer skill is done when:
+
+- A reader who knows the stack would say "yes, that is how you build this here" — not "that is
+  a reasonable summary."
+- It names the **plausible-but-wrong** idioms specific to this stack (the traps a strong
+  general model falls into) and rules them out with reasons.
+- Its references cover the Day-2 baseline in this stack's idiom — including the build/run/debug
+  loop and the test harness, the two affordances a seed lives or dies by.
+- It is self-contained: nothing it needs lives only in your head or only in `docs/principles/`.
+- It would still be right for the tenth bet, not just the first — the rules are general, the
+  examples concrete.

package/src/hidden-skills/groundwork-surface-activation/instructions.md

@@ -0,0 +1,138 @@
+---
+name: groundwork-surface-activation
+description: >
+  Activates a new surface on a live product — the mobile app eighteen months in,
+  the CLI alongside an existing web app. Registers the surface, runs its type's
+  design track when no section for that type exists, scaffolds the app (or records
+  `scaffold: manual`), and triages every capability ledger row so divergence from
+  the existing surfaces is a decision on record, never silent drift. On a
+  pre-restructure product with GroundWork docs but no surface registry, it
+  bootstraps `docs/surfaces.md` first.
+---
+
+# groundwork-surface-activation
+
+Adding a surface to a live product is the moment silent divergence is born. Every capability the product shipped before this surface existed now carries an unasked question — does it reach the new surface, and when? Left unanswered, those questions resolve themselves by accident: the surface launches with whatever subset was convenient, users discover the gaps, and no document can say whether any gap is a plan, a choice, or an oversight.
+
+This skill makes the sync decision deliberate, once, recorded. Steps 1–3 — register, design, scaffold — are the per-surface increments of setup phases that already ran; the ledger triage (Step 4) is the skill's reason to exist: every existing capability row gets the new surface's column filled as `planned`, `omitted`, or `n/a`, and every future bet inherits those decisions instead of re-deciding them from memory.
+
+The registry and ledger contract lives at `.groundwork/skills/templates/surfaces.md`. Read it before touching either artifact — `docs/surfaces.md` and `.groundwork/surfaces.json` are projections of the same decisions, written together in every change this skill makes.
+
+Apply the `groundwork-writer` skill when producing or modifying any document. Declarative, assertive, zero-hedging.
+
+---
+
+## Operating Contract
+
+The shared operating contract at `.groundwork/skills/operating-contract.md` (contract v1) governs this skill. Read it before taking any other action. This is a **Maintenance** skill (see Lifecycle Modes): Protocols 1 (Discovery Notes), 2 (Living Documents), and 4 (Pacing) apply throughout; Protocols 8 and 9 (Review Gate, Review Invocation) fire when a Living Documents update is a reversal — establishing a contract-compatibility stance that overturns an architecture Key Decision is the case this skill is most likely to hit. There is no phase cache, no hand-off file, and no fresh-context recommendation — an activation starts and finishes inside one conversation. From `.groundwork/cache/` it reads only `discovery-notes.md`.
+
+Any working file — a bootstrap reconstruction awaiting the user's confirmation, a triage draft for a long ledger — lives at `.groundwork/cache/surface-activation-draft.md` and is deleted when the activation completes. Final artifacts go to `docs/` and `.groundwork/surfaces.json`, never to the cache.
+
+---
+
+## Registry bootstrap — pre-restructure products only
+
+A product that adopted GroundWork before the surface model exists has canonical docs but no `docs/surfaces.md` — neither the architecture commit nor the brownfield extract wrote a registry for it, so without this bridge it never gains one. When `docs/surfaces.md` does not exist, bootstrap before anything else. When it exists, skip this section entirely — re-running the bootstrap on a registry project would overwrite decisions already on record.
+
+Reconstruct the registry from what the project already proves:
+
+- **`docs/architecture/index.md`** — read its body for the surface detail: it names the services, the surface apps among them, the access paths, and the core's deployment as decided. (This skill runs after setup, so there is no Downstream Context file to read first — the published doc body is the record.)
+- **`docs/architecture/infrastructure.md`** — the scaffold's record of what actually exists: the apps, ports, run commands, test mediums. Where the architecture and the infrastructure doc disagree, the infrastructure doc describes today and wins.
+
+Enter every current surface as `active`, with the fields the docs support: type, platform, core access, auth, scaffold (the generator that produced it, or `manual`), test medium, design-track reference into `docs/design-system.md`. Write the Capability Core section from the deployment as observed. Leave the Capability Ledger **empty — table headers, zero rows**. Reconstructing capability parity from a live product is expensive and fuzzy; an empty ledger is honest ("parity unknown until a bet touches it") where a synthesized one would be confidently wrong. Rows grow per-bet from here, written by bet validation.
+
+Present the reconstruction to the user before writing — the docs cannot reveal everything (the auth model a surface really uses, a half-abandoned app that should enter `dormant`), and a registry born wrong propagates wrong into every consumer. On confirmation, write `docs/surfaces.md` and `.groundwork/surfaces.json` together per the template contract. Then proceed to Step 1 for the new surface.
+
+---
+
+## Step 1: Register
+
+Establish the new surface's registry entry with the user: slug (kebab-case, never renamed — rename means retire and add), type, platform, status, core-access path, auth model, scaffold target, test medium, design-track reference. Most fields are settled by inspection; two are architecture decisions wearing registry fields, and they get a real conversation:
+
+- **Core access.** Direct, gateway, or BFF is asked, not presumed. Surface the trade-space against what the architecture already runs — an existing gateway argues for joining it; a surface with needs the shared API cannot serve cleanly argues for a BFF — and let the user decide.
+- **Auth.** The new surface's auth model against the core, in the architecture's terms. A surface that cannot use the existing auth path (a CLI that needs tokens where the web app uses session cookies) is a real decision, not a field to fill.
+
+**Contract compatibility.** A new surface that deploys independently of the core — and a second deployed artifact does — turns "we changed the contract" from a refactor into an incident the moment release cadences diverge. If `docs/architecture/index.md` carries no contract-compatibility stance, establish one with the user now and record it under the architecture's Binding Constraints via Living Documents. When the stance overturns a committed Key Decision, that is a reversal: the full Reversal Protocol applies, review re-gate included.
+
+Write the registry entry and the JSON twin in the same change.
+
+## Step 2: Design
+
+A surface needs its type's design vocabulary, not a design system of its own. When `docs/design-system.md` already carries a section for the surface's type, design is done — point the registry's design-track reference at it and move on; type sections are shared by every surface of that type.
+
+When no section for the type exists, run the type's track lazily against the existing foundation: load the track file at `.groundwork/skills/groundwork-design-system/tracks/<type>.md` and execute its Phase 5 in full — translation, independent review, guided walkthrough. The brand conversation (the foundation's Phases 1–4) ran once at setup and is not re-run: a product has one personality no matter how many types express it. This skill stands in for the foundation flow the track normally returns to — where the track expects the brand synthesis from the design-system cache, read the committed foundation sections of `docs/design-system.md` instead (they are the durable form of the same decisions), and the commit below replaces the foundation's Phase 6.
+
+On the user's approval, append the new type section to `docs/design-system.md` and add the type's Tier 2 block to `.groundwork/config/brand-tokens.json` (`terminal` from the cli track, `visual` from graphical-ui; agentic-protocol contributes none), following the contract at `.groundwork/skills/groundwork-design-system/templates/brand-tokens.md`. The block carries the same values as the section just written — a mechanical projection, not a second conversation. Delete the track's draft directory (`.groundwork/cache/design-system-draft/`) once the section is committed.
+
+## Step 3: Scaffold
+
+When the surface's `scaffold` field names a generator, generate the app: one invocation, named by the surface's slug, parameters per the per-surface pattern in `.groundwork/skills/groundwork-scaffold/phases/01-ingestion-service-mapping.md` — its Generator Capability Mapping table is the contract between architectural language and generator flags. Confirm the invocation with the user before running it; fixing generated code is harder than correcting a flag.
+
+When the field is `manual`, no generator runs. `manual` is first-class — the surface participates fully in design, bets, the ledger, and tests before tooling exists for its platform.
+
+Either way, the operational expectations are the same and go on the record: a health endpoint (or the medium's equivalent liveness probe), `./dev` integration so the surface boots with the rest of the topology, and registration in the `surfaces` test fixture — re-invoke `system-test-runner --surfaces` with the full active set from `.groundwork/surfaces.json` so the fixture map gains the new slug with its medium and reach. For a generated surface these arrive with the scaffold; for a manual surface they are obligations its implementation must meet to keep the registration honest. Update `docs/architecture/infrastructure.md`'s Surfaces group with the new entry either way (Living Documents).
+
+## Step 4: Triage the ledger
+
+The step that earns this skill its existence. Walk every existing capability row with the user and fill the new surface's column. Each cell takes exactly one state:
+
+- `planned` — will ship here; carries a bet ref or a discovery-notes pointer. The `planned` cells are the new surface's bet backlog.
+- `omitted` — a deliberate product decision not to ship here, with a one-line rationale a future bet may revisit.
+- `n/a` — structurally meaningless on this surface; no payload.
+
+No cell is left empty — an empty cell is an undecided divergence, the exact thing this skill exists to prevent. `delivered` is not a triage outcome: nothing has shipped on a surface that was just born. The one exception is registering an artifact that already exists and already carries a capability (a brownfield CLI brought into the registry late) — there `delivered` is legal with the delivering bet named, claimed only where the evidence exists.
+
+Pace the walk as proposals, not interrogation. Read the rows, propose dispositions for clusters of related capabilities with the reasoning attached, and let the user react. Row-by-row questioning exhausts the user before the interesting decisions arrive; per-cluster proposals surface the pattern and reserve conversation for the rows where the user pushes back. Every row still gets decided — clustering is pacing, not skipping.
+
+Update both registry twins in the same change: the prose ledger gains the column, and every entry in `.groundwork/surfaces.json`'s `capabilities` array gains a cell keyed by the new slug — a missing cell key is the machine form of the illegal empty cell.
+
+On a bootstrap run the ledger has headers and zero rows, so the triage is complete by construction. Say so plainly; do not invent rows. The honest-unknown stance holds — rows arrive as bets touch capabilities.
+
+## Step 5: Hand off
+
+`planned` cells are commitments, and commitments that live only in a table get rediscovered instead of delivered. Cross-post every `planned` cell as a bullet under `## Bets` in `.groundwork/cache/discovery-notes.md`, naming the capability key and the target surface — bet discovery reads that section, so each deferral becomes candidate scope for the next pitch instead of a memory. Ordinary bets deliver them; activation never starts delivery itself.
+
+Close out:
+
+1. **Report what the activation produced**: the registry entry (and the bootstrap, when it ran), the design section appended or found existing, the scaffold result (generator output, or the manual obligations recorded), the triage in numbers (rows walked, cells per state), the discovery-notes entries added, and every doc updated via Living Documents.
+2. **Capture stray signals** under their headers in `.groundwork/cache/discovery-notes.md` (Protocol 1).
+3. **Delete** `.groundwork/cache/surface-activation-draft.md` if it was created.
+4. Hand off to the `groundwork-orchestrator` skill.
+
+---
+
+## Quality Standard: What a Real Triage Looks Like
+
+The triage fails when it fills cells without recording decisions. A column of bare states is a parity nag wearing a ledger — it points nowhere, and the next bet inherits nothing.
+
+**Shallow triage (insufficient):**
+
+```markdown
+| Capability | web-app | support-cli |
+|---|---|---|
+| `order-flow/place-order` | delivered (`order-flow`) | planned |
+| `order-flow/order-status` | delivered (`order-flow`) | planned |
+| `account-recovery/reset-credentials` | delivered (`account-recovery`) | planned |
+| `storefront/theme-preview` | delivered (`storefront`) | planned |
+```
+
+Every cell `planned`, no refs, no rationale, nothing cross-posted to discovery notes, the JSON twin untouched. No decision was made — the column says "sync everything eventually," which is the silent drift the triage exists to replace, now with a timestamp.
+
+**Deep triage (required standard):**
+
+```markdown
+| Capability | web-app | support-cli |
+|---|---|---|
+| `order-flow/place-order` | delivered (`order-flow`) | omitted — operators support orders, they never place them |
+| `order-flow/order-status` | delivered (`order-flow`) | planned (discovery-notes — first capability the support team asked for) |
+| `account-recovery/reset-credentials` | delivered (`account-recovery`) | planned (discovery-notes — pairs with order-status in one support bet) |
+| `storefront/theme-preview` | delivered (`storefront`) | n/a |
+```
+
+Plus, in the same change: two `## Bets` bullets in discovery notes naming each capability key and the target surface with the reasoning, and every `capabilities` entry in `.groundwork/surfaces.json` gaining a `support-cli` cell with identical states and payloads. Every column decided, every decision findable.
+
+The same depth standard applies to the other outputs:
+
+- **Registry entries** carry every field with a real value — an `active` surface with no test medium, or a design-track reference pointing at a section that does not exist, is an entry that will fail its first consumer.
+- **The bootstrap** names what each reconstructed field was read from (which architecture decision, which infrastructure row) so the user confirms evidence, not guesses.
+- **Manual-scaffold obligations** are concrete and checkable — the health endpoint's path, the `./dev` target, the fixture slug — not a sentence saying the surface should integrate eventually.