@static-var/keystone 0.1.0

package/skills/keystone/modules/helpers/subagents.md

@@ -0,0 +1,134 @@
+# Keystone Subagents and Reasoning Helper
+
+## Purpose
+Teach Keystone when subagents can be used, which hosts support them, and what reasoning level each Keystone module should prefer.
+
+This helper is advisory. Host capability wins over Keystone preference. If the current harness cannot set reasoning per subagent, encode the desired reasoning in the subagent prompt or do the work inline.
+
+## Delegation rule
+Use subagents only when the task has a clear boundary and a useful handoff artifact.
+
+Good delegation targets:
+- read-only reconnaissance
+- independent implementation slices
+- focused debugging/root-cause analysis
+- read-only review
+- documentation/copy drafting
+
+Do not delegate when:
+- the task needs tight conversational clarification
+- one agent must continuously coordinate shared mutable state
+- the host cannot preserve enough context for safe handoff
+- the subagent would need secrets or permissions the parent should not share
+- delegation setup, context packaging, merge/review effort, or verification overhead is likely greater than doing the task inline
+
+## Delegation cost heuristic
+
+Before spawning a subagent, compare expected benefit with coordination cost.
+
+Delegate when at least one is true:
+- the subtask can run in parallel with other independent work
+- the subtask requires a different role, perspective, or reasoning depth
+- the repository/source search is large enough that a scout can save parent context
+- independent review or root-cause analysis materially reduces release risk
+
+Do not delegate when most of these are true:
+- the task can be done inline in a few minutes
+- the parent would need to explain more context than the subagent can save
+- outputs will require complex merge arbitration
+- the work touches the same mutable files as another active agent without isolation
+- verification cannot be independently stated in the prompt
+
+If uncertain, prefer one narrow read-only scout/reviewer over multiple workers.
+
+## Host capability matrix
+
+| Harness | Subagents | Per-subagent reasoning/effort | How to configure | Keystone policy |
+|---|---:|---:|---|---|
+| Pi coding agent with `pi-subagents` | yes | yes | `.pi/agents/<name>.md` frontmatter `model`, `thinking`, `profile`, or `Agent({ subagent_type, thinking, model, profile })` | Use native roles; prefer role defaults unless Keystone needs a one-off override. |
+| Claude Code | yes | partial | `.claude/agents/<name>.md` supports subagent config and `model`; built-in Explore accepts quick/medium/very-thorough style detail, but custom agents do not expose a general reasoning knob | Use `model` plus explicit prompt instructions; use built-in Explore detail when applicable. |
+| Codex CLI/app | unclear/host-dependent | partial/global | known global config includes `model_reasoning_effort`; no stable per-subagent effort schema confirmed | Treat Keystone reasoning as advisory text unless the active Codex host exposes a per-agent effort control. |
+| T3 Code | not confirmed | not confirmed | no confirmed public/local schema | Treat as unsupported; run inline or through the underlying Claude/Codex/OpenCode provider if available. |
+| OpenCode | yes | partial/provider-dependent | agent config supports `mode: "subagent"`, `model`, and provider-specific `variant`; no universal reasoning field is confirmed | Use subagent mode; map Keystone reasoning to model/variant only where the provider exposes effort variants, otherwise write the desired reasoning in the prompt. |
+| GitHub Copilot / VS Code | yes | partial | `.github/agents/*.agent.md` supports `model`, `agents`, `user-invocable`, `disable-model-invocation`; no general reasoning knob found | Use custom agents and model choice; put reasoning expectation in the agent prompt. |
+
+## Canonical reasoning scale
+
+Keystone uses this host-neutral scale:
+
+| Level | Use for |
+|---|---|
+| `off` | deterministic formatting, mechanical edits, no reasoning needed |
+| `minimal` | tiny lookups, simple classification, trivial copy changes |
+| `low` | ordinary reading, straightforward writing, small scoped tasks |
+| `medium` | normal implementation, UI decisions, moderate research |
+| `high` | architecture, debugging, review, planning, ambiguous tradeoffs |
+| `xhigh` | hard root-cause analysis, security-sensitive review, major design decisions |
+
+If a host uses another vocabulary, map to the nearest equivalent. If no setting exists, write the desired level into the prompt, for example: "Use high reasoning; explore alternatives before deciding."
+
+## Keystone module defaults
+
+| Keystone file | Preferred role | Default reasoning | Escalate when |
+|---|---|---:|---|
+| `modules/router.md` | none or lightweight classifier | `low` | request is ambiguous across several irreversible actions |
+| `modules/research.md` | scout/read-only explorer or oracle | `medium` | repository is large, source relationships are unclear, or claims affect architecture, market, safety, or release decisions (`high`) |
+| `modules/shape.md` | writer, UI/design reviewer, or oracle | `medium` | visual systems, accessibility, complex positioning, architecture, product viability, or irreversible scope decisions are involved (`high`/`xhigh`) |
+| `modules/breakdown.md` | planner plus reviewer | `high` | plan spans multiple independent agents or risky sequencing (`xhigh`) |
+| `modules/build.md` | worker | `medium` | concurrency, migrations, broad refactors, or unfamiliar stack (`high`) |
+| `modules/debug.md` | oracle/root-cause investigator | `high` | intermittent, cross-system, performance, or data-loss failures (`xhigh`) |
+| `modules/review.md` | reviewer/read-only | `high` | security, release, data migration, or public API review (`xhigh`) |
+| `modules/ship.md` | ship coordinator | `medium` | release has unresolved risk or multi-host packaging (`high`) |
+| `modules/health.md` | scout plus reviewer | `medium` | broad repository/tooling drift or release readiness audit (`high`) |
+| `modules/gates/*.md` | none | `low` | evidence is contradictory or safety-critical (`medium`) |
+
+## Pi role mapping
+
+When Pi subagents are available, use the narrowest role and usually keep its configured defaults:
+
+| Need | Pi role | Typical thinking |
+|---|---|---:|
+| codebase exploration | `scout` | `low` |
+| implementation | `worker` | `medium` |
+| code/spec review | `reviewer` | `high` |
+| architecture/root-cause second opinion | `oracle` | `high` or `xhigh` |
+| docs/copy | `writer` | `low` |
+
+Only override `thinking` when the module table says to escalate or de-escalate.
+
+## Safe parallel work pattern
+
+1. `breakdown` identifies independent tasks and their verification commands.
+2. `build` passes `gates/isolation.md` before any mutation.
+3. If the host supports isolated worktrees, each worker gets a separate worktree or host-isolated workspace.
+4. Each worker reports files changed, tests run, and concerns.
+5. Parent reconciles outputs before further mutation: accept, reject, or send back with a narrower prompt.
+6. `review` runs as read-only, preferably in a separate reviewer subagent.
+7. `ship` finalizes only after proof and review gates pass.
+
+## Prompt contract for delegated work
+
+Every subagent prompt should include:
+
+- exact task scope
+- files or areas allowed to change/read
+- protected files
+- expected output artifact or report
+- reasoning level requested if the host cannot enforce it
+- verification command expected
+- instruction not to broaden scope
+- timeout or stopping condition when the host supports it
+
+For read-only subagents, explicitly say: "Do not edit files." For review subagents, explicitly say: "Return findings only; do not fix."
+
+## Subagent result handling
+
+Treat subagent output as evidence, not truth. The parent remains responsible for verification and final routing.
+
+- Timeout or no response: mark the subtask incomplete, preserve any partial logs, and either finish inline or re-delegate with a smaller scope if the remaining work is still worth the overhead.
+- Bad output or scope creep: reject the result, record why, and re-delegate only with a tighter prompt, protected-file list, and explicit expected artifact. Otherwise do it inline.
+- Partial completion: accept only independently verified pieces; carry unfinished work in the handoff packet with files touched, tests run, and remaining risks.
+- Conflicting outputs: compare evidence and reproduction/proof commands first. If both are plausible and risk is material, ask an oracle/reviewer for read-only arbitration or route to `debug`; do not merge contradictory fixes blindly.
+- Failed verification: route through the appropriate Keystone module (`debug` for unexplained failures, `build` for contained fixes, `review` for risk assessment) and rerun the original proof before continuing.
+
+Re-delegate only when the next prompt can be narrower than the failed one, the expected artifact is concrete, and the benefit still exceeds coordination cost. Otherwise continue inline and record the reason.

package/skills/keystone/modules/research.md

@@ -0,0 +1,86 @@
+# Keystone Research Module
+
+## Core principle
+Research is evidence gathering before action. Inspect available material first, preserve source quality, separate facts from assumptions, and do not mutate the project unless the user explicitly asks for a durable research artifact.
+
+## Load when
+Load when the user asks to read, inspect, summarize, inventory, extract, compare, explain, investigate options, gather technical or market context, validate claims, or answer “what is true here?” before a decision.
+
+## Not for
+- Implementing, refactoring, editing, or fixing code.
+- Shaping product direction beyond evidence-backed options.
+- Broad tooling risk audits; use `health`.
+- Root-cause repair of a failure; use `debug` after initial context.
+- Guessing when evidence can be inspected.
+
+## Outcome contract
+Deliver a research brief that states:
+- question or decision being supported;
+- sources inspected, with file paths, commands, URLs, or other citations;
+- source-quality notes (primary vs secondary, current vs stale, authoritative vs anecdotal);
+- findings separated from assumptions and unknowns;
+- confidence level and why;
+- recommended next module or no-op if no action is warranted.
+
+## Modes
+- **Repository read:** inspect files, history, configs, tests, docs, and existing behavior. Prefer primary project evidence.
+- **External research:** compare outside documentation, standards, issues, market examples, or APIs. Cite URLs and note recency.
+- **Synthesis:** combine several sources into a decision-ready summary with tradeoffs and confidence.
+- **Discovery scout:** map a large unknown area without drawing strong conclusions until evidence is sampled.
+
+## Process
+1. Restate the research question and the decision it informs.
+2. Inspect before asking: search/read the repo, docs, logs, or provided sources before requesting more context.
+3. Prefer primary evidence: source code, tests, product docs, official docs, reproducible commands, direct user-provided material.
+4. Track citations as you go. Every important claim should point to evidence or be labeled as an assumption.
+5. Evaluate source quality: age, authority, completeness, bias, and whether evidence is direct or inferred.
+6. Compare alternatives when relevant, including costs, risks, constraints, and no-op implications.
+7. State unknowns explicitly. Do not fill gaps with confident-sounding speculation.
+8. Recommend the smallest next step: `shape`, `debug`, `health`, `breakdown`, `build`, `review`, or stop.
+
+## Subagents and reasoning
+Default reasoning: `medium`. Use read-only scout subagents when the search space is large or evidence can be gathered independently. Use `low` for narrow file summaries. Use `high` when findings affect architecture, security, safety, release decisions, legal/market claims, or irreversible product direction. Subagents must remain read-only unless the user requested an artifact.
+
+## Hard rules
+- No mutation by default: do not edit files, run formatters, or alter state except harmless read-only commands.
+- Cite evidence for material claims; if evidence is unavailable, say so.
+- Distinguish facts, interpretations, assumptions, and recommendations.
+- Do not ask for information that can be inspected first.
+- Do not present search results or model knowledge as authoritative without source-quality caveats.
+
+## Failure modes
+- **Context theater:** long summaries without citations or decision relevance.
+- **Source laundering:** treating blogs, stale docs, or guesses as facts.
+- **Premature shaping:** deciding product behavior before evidence is clear.
+- **Mutation creep:** “just fixing” or rewriting while researching.
+- **Hidden uncertainty:** omitting confidence, unknowns, or contradictory evidence.
+
+## Worked example
+Good research finding: “Official Stripe docs show idempotency keys apply per unique key and preserve the first result, including failures; this means retrying payment capture should reuse the original key, not generate a new one. Confidence: High — primary docs, current page.”
+
+Bad research finding: “Stripe probably handles retries safely, so we can just retry the request.”
+
+## Output format
+```markdown
+## Research brief
+Question: ...
+
+### Evidence inspected
+- `path/or/source`: what it shows, quality note
+
+### Findings
+- Fact — citation
+- Interpretation — citation + reasoning
+
+### Assumptions / unknowns
+- ...
+
+### Options or implications
+- ...
+
+### Confidence
+High/Medium/Low — why
+
+### Recommended next step
+Module or no-op, with rationale
+```

package/skills/keystone/modules/review.md

@@ -0,0 +1,270 @@
+# Keystone Review Module
+## Core principle
+Review is an independent, read-only attempt to disprove readiness.
+
+Ask two questions at the same time:
+1. **Spec axis:** does the work satisfy the stated requirements and acceptance criteria?
+2. **Standards axis:** is it secure, correct, maintainable, tested, and safe to operate?
+
+Do not assume changed lines are the blast radius. Trace callers, callees, contracts,
+data flow, tests, runtime paths, and user impact before giving a verdict.
+
+## Load when
+Load when the user asks for code review, critique, audit, readiness assessment,
+release/merge review, security review, regression review, or review of a diff, branch,
+PR, patch, migration, fix, plan output, or completed implementation.
+
+Also load when another Keystone module needs `gates/review.md` satisfied before ship.
+
+## Not for
+Do not use Review for:
+- fixing, refactoring, formatting, or rewriting code
+- committing, merging, tagging, publishing, or shipping
+- initial implementation planning before a reviewable artifact exists
+- open-ended research with no concrete artifact to assess
+- debugging where the requested outcome is a fix
+
+If asked to review and fix, review first, stop, and hand findings to `build`, `debug`,
+`research`, `ship`, or a human only after explicit permission.
+
+## Outcome contract
+A complete review returns:
+- verdict: **Block**, **Caution**, or **Looks good**
+- findings ordered P0, P1, P2, P3, then Nitpicks
+- evidence for every finding: file/line, behavior path, contract, test, log, or doc
+- user impact and why the severity is justified
+- remediation guidance without applying the fix
+- tests that should be added or updated for affected behavior
+- scope reviewed, validation run, limitations, and read-only confirmation
+
+The review is incomplete if it only inspects the diff, only comments on style, or
+cannot explain how the work behaves at runtime.
+
+## Review passes
+Perform multiple passes. New evidence from one pass expands later passes.
+### Pass 0: scope and baseline
+- Identify artifact reviewed: diff, branch, files, release candidate, or plan result.
+- Read the user request, issue, spec, acceptance criteria, and claimed completion.
+- Check repository status without modifying files.
+- Record uncommitted work as context, not cleanup.
+
+### Pass 1: spec compliance
+- Compare implementation against explicit requirements and non-goals.
+- Check edge cases, error states, and acceptance criteria.
+- Separate spec misses from standards concerns.
+- Treat a clean implementation of the wrong behavior as a finding.
+
+### Pass 2: correctness and runtime paths
+- Trace primary success and failure paths end to end.
+- Follow changed functions into helpers, services, adapters, persistence, UI, jobs, and
+  serializers.
+- Validate inputs, outputs, invariants, state transitions, retries, ordering,
+  concurrency assumptions, and error propagation.
+- Look for nullability, off-by-one, time, encoding, pagination, caching, idempotency,
+  cancellation, and partial-failure issues.
+
+### Pass 3: regression and compatibility
+- Identify callers, consumers, and workflows that rely on old behavior.
+- Check public APIs, CLIs, schemas, migrations, persisted data, environment variables,
+  feature flags, configuration defaults, and documentation.
+- Consider rollback, downgrade, mixed-version, and incremental rollout risks.
+- Search for tests or fixtures that encode previous behavior.
+
+### Pass 4: security, privacy, and abuse resistance
+- Review authentication, authorization, tenancy, secrets, logging, validation,
+  injection, XSS, SSRF, path traversal, unsafe deserialization, and RCE surfaces.
+- Check whether sensitive data leaks through errors, logs, telemetry, URLs, caches,
+  exports, screenshots, or third-party calls.
+- Consider malicious users, compromised clients, replay, races, resource exhaustion,
+  privilege escalation, and denial of service.
+
+### Pass 5: tests and proof
+- Map changed behavior to existing tests.
+- Identify missing unit, integration, contract, regression, migration, security,
+  accessibility, performance, or end-to-end coverage.
+- Prefer behavior assertions over implementation trivia.
+- Run focused read-only validation when practical: existing tests, type checks, lint,
+  builds, or targeted commands.
+- If validation cannot run, state why and what should be run.
+
+### Pass 6: maintainability and architecture
+- Assess clarity, cohesion, naming, dependency direction, duplication, complexity,
+  observability, and debuggability.
+- Check architectural boundaries, local conventions, and API contracts.
+- Flag brittle abstractions, hidden coupling, unnecessary cleverness, and premature
+  generalization when they create real maintenance risk.
+
+### Pass 7: user impact and final consistency
+- Translate technical issues into affected personas, workflows, data, accessibility,
+  performance, reliability, and support burden.
+- Re-rank findings by blast radius, likelihood, recoverability, and detectability.
+- De-duplicate findings, verify evidence, and state limitations honestly.
+
+## Severity rubric
+Severity reflects realistic impact, not fix size.
+
+### P0: Critical blocker
+Immediate or likely severe harm. Examples:
+- data loss, corruption, or irreversible destructive action
+- unauthorized access, privilege escalation, secret exposure, or major privacy breach
+- production outage or release artifact that cannot safely deploy
+- legal/compliance risk with material impact
+
+P0 means do not ship or merge without accountable human acceptance and mitigation.
+
+### P1: Blocking defect
+High-impact issue that violates core requirements or creates serious regression risk.
+Examples:
+- primary workflow broken for a meaningful user segment
+- incorrect billing, permissions, persistence, or business logic
+- migration or compatibility gap that can break real deployments
+- high-risk behavior lacking tests plus a plausible failure mode
+
+P1 normally blocks ship.
+
+### P2: Important non-blocker or conditional blocker
+Material issue with bounded impact, lower likelihood, or workaround. Examples:
+- edge case with clear user impact
+- moderate-risk test gap
+- maintainability issue likely to cause near-term bugs
+- weak observability for a risky path
+
+State whether release context makes it blocking.
+
+### P3: Low-risk improvement
+Valid concern with limited impact. Examples:
+- confusing name or local complexity that slows future work
+- minor non-hot-path performance inefficiency
+- incomplete docs for non-critical behavior
+- small test organization weakness
+
+P3 should not block unless it compounds with related risks.
+
+### Nitpick
+Cosmetic, preference-level, or optional feedback: unenforced formatting, wording tweaks,
+or style suggestions with no correctness or maintainability impact. Keep nitpicks
+separate from severity findings.
+
+## Impact tracing
+For each meaningful change, trace:
+- **Entry points:** user action, API route, CLI, job, event, hook, or import.
+- **Callers:** who invokes this and what assumptions they make.
+- **Callees:** helpers, libraries, persistence, network calls, and side effects.
+- **Data flow:** input, validation, transformation, storage, serialization, output.
+- **Contracts:** types, schemas, public APIs, flags, config, docs, and errors.
+- **Runtime paths:** success, failure, retry, timeout, cancellation, concurrency.
+- **Tests:** existing coverage, missing assertions, fixtures, mocks, snapshots.
+- **Users:** visible behavior, accessibility, performance, reliability, trust.
+
+If tracing leaves uncertainty, gather more read-only evidence or report the limitation.
+Do not invent confidence.
+
+## Security and regression checklist
+Ask for every non-trivial review:
+- Can a user access, modify, infer, or delete data they should not?
+- Are authn, authz, tenancy, and ownership checked at the right layer?
+- Can untrusted input reach queries, interpreters, shells, paths, templates, redirects,
+  or deserializers unsafely?
+- Are secrets, tokens, PII, or internal identifiers exposed in logs, errors, telemetry,
+  URLs, caches, or client bundles?
+- Did defaults, permissions, feature flags, or safeguards become unsafe?
+- Are races, duplicate submissions, retries, replay, and out-of-order events safe?
+- Can persisted data be corrupted, stranded, or made hard to rollback?
+- Are public APIs, stored data, configs, and integrations backward compatible?
+- Does failure degrade safely without hidden partial success?
+- Are performance, resource use, accessibility, localization, and platform differences
+  acceptable for realistic users and abuse?
+- Do tests cover the affected behavior and important regression paths?
+
+## Subagents and reasoning
+Default reasoning: `high`.
+
+Use read-only reviewer subagents for separable risks: security/privacy, test coverage,
+architecture/API compatibility, persistence/migration, accessibility/user impact,
+performance, concurrency, or release risk. Escalate to `xhigh` for security-sensitive,
+data-loss, billing, permissions, public API, migration, or cross-system reviews.
+
+Subagents must receive the read-only contract and return evidence-backed findings, not
+patches. Reconcile duplicates and conflicts before reporting. The primary reviewer
+owns final severity and verdict.
+
+## Hard rules
+- Read-only only: do not edit, format, generate, stage, commit, merge, tag, publish,
+  or ship files.
+- Do not silently fix issues discovered during review.
+- Do not run destructive or project-mutating commands.
+- Do not rely only on changed lines; inspect impacted code paths and contracts.
+- Do not approve solely because tests pass.
+- Do not report speculation as fact; mark uncertainty.
+- Do not bury blockers under minor comments.
+- Do not disguise style preferences as correctness findings.
+- Do not omit needed tests when behavior changed.
+- Do not satisfy `gates/review.md` unless blockers and non-blockers are separated.
+
+## Failure modes
+Avoid these anti-patterns:
+- **Single-pass skim:** one read of changed lines plus generic comments.
+- **Diff tunnel vision:** missing callers, callees, contracts, and user impact.
+- **Checklist theater:** naming security/tests without tracing actual risk.
+- **Green-test rubber stamp:** assuming current tests prove new behavior.
+- **Spec blindness:** judging code quality while requirements are unmet.
+- **Standards blindness:** accepting unsafe or fragile code because the narrow spec passes.
+- **Severity inflation:** turning preferences into blockers.
+- **Severity deflation:** downgrading real user harm because the fix is small.
+- **Patch creep:** fixing, refactoring, or committing instead of reviewing.
+- **Unowned uncertainty:** failing to state what was not verified.
+
+## Output format
+Worked finding example:
+```markdown
+### P1
+- Missing tenant check on invoice export
+  - Evidence: `api/exportInvoice.ts:42` accepts `invoiceId` and loads the invoice without comparing `invoice.accountId` to the authenticated account; `/invoices/:id/export` is reachable by any logged-in user.
+  - Impact: A user who guesses another invoice ID can download billing data from a different account, which is a privacy and authorization breach.
+  - Recommendation: Enforce tenant ownership before export and return the existing unauthorized response on mismatch.
+  - Tests needed: Add an integration test where account A requests account B's invoice and receives 403/no file, plus a happy-path same-account export test.
+```
+
+Use this structure:
+```markdown
+## Verdict
+Block | Caution | Looks good
+
+## Scope reviewed
+- Artifact reviewed:
+- Key files/paths inspected:
+- Validation run:
+- Review limitations:
+- Read-only confirmation: no files changed by this review
+
+## Findings
+### P0
+- [Title]
+  - Evidence:
+  - Impact:
+  - Recommendation:
+  - Tests needed:
+### P1
+None
+
+### P2
+None
+
+### P3
+None
+
+## Nitpicks
+None
+
+## Tests to add or update
+- Behavior:
+  - Suggested coverage:
+  - Why it matters:
+## Handoff
+- Blockers:
+- Non-blocking follow-up:
+- Suggested owner module: build, debug, research, ship, or human
+```
+
+If a severity has no findings, write `None`. Recommendations must be actionable but
+must not be applied by Review.

package/skills/keystone/modules/router.md

@@ -0,0 +1,36 @@
+# Keystone Router Module
+
+## Intent
+Classify the user's request and select one Keystone primary module.
+
+## Load when
+The task is ambiguous, explicitly asks for routing, or starts from `/keystone` without a clear module fit.
+
+## Allowed mutation
+None, except writing a short routing decision in the conversation.
+
+## Must not
+Modify files, perform implementation, or expose internal modules as public slash commands.
+
+## May call
+One primary module after classification. Gates only if that primary module requires them.
+
+## Subagents and reasoning
+Default reasoning: `low`. Do not deploy subagents for simple routing; ask one clarifying question if a safe single route is not clear. See `helpers/subagents.md`.
+
+## Routing heuristics
+Prefer the module indicated by the user's strongest current need, not the first verb alone. Weigh multiple signals together:
+- Failure, error, broken behavior, repro, or "fix" language points to `debug` before implementation.
+- Review, verify, approve, merge, or ship language points to `review` before release or cleanup.
+- New capability requests route by maturity: use `shape` when intent is fuzzy, `breakdown` when the outcome is clear but work needs decomposition, and `build` when scope and acceptance criteria are already concrete.
+
+## Disambiguation examples
+- "debug this and fix it" -> select `debug`; establish cause before changing code.
+- "review and ship" -> select `review`; verify readiness before any shipping step.
+- "add feature" -> select `shape`, `breakdown`, or `build` based on maturity; ask one concise clarifying question if maturity is not inferable.
+
+## Handoff
+Name the selected primary module and the reason in one sentence, then continue under that module's contract.
+
+## Exit gate
+Exactly one primary module is selected, or one clarifying question is asked.

package/skills/keystone/modules/shape.md

@@ -0,0 +1,125 @@
+# Keystone Shape Module
+
+## Core principle
+Shape is a specification algorithm: turn an unclear intent into exact behavior, constraints, tradeoffs, and acceptance criteria before anyone builds. It decides what should be true, not whether code is complete.
+
+## Load when
+Load when the user asks to draft, rewrite, design, spec, define product behavior, improve UI/UX, choose visual direction, name or explain a feature, make scope or architecture tradeoffs, prepare acceptance criteria, or turn research into an implementation-ready direction.
+
+## Not for
+- Writing implementation code or changing runtime behavior; hand off to `build`.
+- Diagnosing failures; use `debug`.
+- Broad repository health or release readiness; use `health` or `ship`.
+- Inventing facts that should be researched first.
+- Polishing completed work as shippable proof.
+
+## Outcome contract
+Deliver a shaped proposal that includes:
+- goal, user/audience, and success criteria;
+- product behavior and UX states, including happy, empty, loading/pending, error/failure, and edge/constraint states where relevant;
+- copy or content direction when user-facing text matters;
+- architecture and scope tradeoffs at the level needed for planning, not implementation;
+- alternatives considered and why one direction is preferred;
+- acceptance criteria and non-goals;
+- recommended next module (`breakdown`, `build`, `review`, `research`, or no-op).
+
+## Modes
+- **Product shape:** specify the user job, trigger, actor permissions, core flow, business rules, constraints, success metrics, non-goals, and acceptance criteria.
+- **UX/UI shape:** specify layout hierarchy, navigation, interaction model, responsiveness, accessibility, visual constraints, and the 5-state UX checklist: happy, empty, loading/pending, error/failure, edge/constraint.
+- **Copy shape:** specify audience, message hierarchy, claims, tone, CTA, labels, empty/error text, and prohibited vague claims.
+- **Technical shape:** specify boundary placement, API granularity, data flow, state ownership, dependency direction, persistence/integration seams, and architectural tradeoffs without writing code.
+- **Alternative exploration:** present multiple viable directions before choosing or asking the user to choose.
+
+## Process
+1. Classify the request into one or more modes: product, UX/UI, copy, technical, or alternatives.
+2. Identify the goal, primary user/audience, job-to-be-done, context of use, and success criteria.
+3. Inspect existing product patterns, domain language, and provided material before inventing new conventions.
+4. Convert intent into exact rules:
+   - Product: actor, trigger, preconditions, action, result, permissions, limits, and measurable success.
+   - UX/UI: screen/region hierarchy, controls, transitions, accessibility behavior, responsive behavior, and 5-state UX checklist.
+   - Copy: exact headline/body/CTA/error text or content rules, with claims grounded in known facts.
+   - Technical: components/modules involved, ownership boundaries, contracts, data flow, failure handling, migration or rollout constraints.
+5. Apply technical shaping heuristics when architecture matters:
+   - **Boundary placement:** put boundaries where ownership, volatility, testability, or external systems change; do not split stable one-step logic.
+   - **API granularity:** prefer operations that match caller intent; avoid both chatty micro-methods and god endpoints that hide unrelated behavior.
+   - **Data flow:** name source of truth, state transitions, sync/async edges, validation points, and where errors surface.
+   - **Architectural tradeoffs:** state what becomes simpler, harder, slower, safer, more testable, or more coupled.
+6. Ban fluffy terms unless translated to behavior. Words like “modern,” “clean,” “intuitive,” “delightful,” “seamless,” or “user-friendly” must become observable rules.
+7. Offer alternatives when the direction is not obvious. Include the no-op option if legitimate.
+8. Convert the chosen direction into acceptance criteria that can be implemented and reviewed.
+9. Stop at the spec boundary. If the user asks for design plus build, finish Shape with the spec and recommended handoff to `build`; do not implement code.
+
+## Subagents and reasoning
+Default reasoning: `medium`. Use writer, UI, design, or architecture subagents for bounded alternatives, critique, or parallel concepts. Use `high` for multi-screen flows, accessibility-sensitive experiences, design-system impact, pricing/positioning, architecture boundaries, or major scope decisions. Subagents should produce options or critique, not unrequested implementation.
+
+## Hard rules
+- Shape is not build: do not edit production code or runtime behavior.
+- If the user asks for design and implementation together, Shape stops after the specification and hands off to `build`.
+- Ground claims in research or existing product evidence; call `research` when facts are missing.
+- Always identify user/audience and success criteria for product-facing work.
+- Include acceptance criteria before handing off to implementation.
+- Translate fluffy descriptors into exact behavior; otherwise remove them.
+- Avoid no-op avoidance: if the best answer is “do nothing” or “decide later,” say so with criteria.
+
+## Failure modes
+- **Abstract advice:** principles without actors, states, rules, tradeoffs, or acceptance criteria.
+- **Pretty but unusable:** visual ideas without behavior, states, or acceptance criteria.
+- **Fluffy spec:** “modern/user-friendly” language without exact behavior.
+- **Spec as proof:** implying a design solves the problem before implementation or validation.
+- **Audience blur:** writing for everyone and satisfying no one.
+- **Scope fog:** hiding hard tradeoffs until build time.
+- **Premature code:** implementing while still deciding what should exist.
+
+## Examples
+Good product shape: “When a workspace has no projects, show an empty state with title ‘Create your first project,’ one-sentence explanation, primary ‘New project’ CTA, and no table chrome. Success: first project creation rate increases.”
+Bad product shape: “Make the dashboard more useful and modern.”
+
+Good UX/UI shape: “On save, disable the Save button, keep the form editable fields visible, show inline progress text ‘Saving…’, then restore focus to the first invalid field on failure.”
+Bad UX/UI shape: “Use a clean, user-friendly save experience.”
+
+Good copy shape: “CTA says ‘Start free trial’ because billing is not required; avoid ‘Buy now.’ Error text names the failed action and recovery: ‘We couldn’t send the invite. Check the email address and try again.’”
+Bad copy shape: “Use friendly copy that reduces friction.”
+
+Good technical shape: “Keep validation in the domain service because API and background import both need it; expose one `createInvite` operation that returns accepted, duplicate, or invalid-email outcomes.”
+Bad technical shape: “Add a helper/manager layer so the architecture is scalable.”
+
+Worked technical shape: “For export retries, keep the queue worker as the owner of retry state, expose `requestExport(accountId, format)` from the API, persist `pending|running|failed|ready` status in `exports`, and surface failures through the existing job status endpoint. Tradeoff: one extra status read, but retry policy stays out of controllers and can be tested without HTTP.”
+
+## Output format
+```markdown
+## Shaped direction
+Goal: ...
+Audience/user: ...
+Mode(s): product | UX/UI | copy | technical | alternatives
+
+### Proposed behavior / experience
+- Actor/trigger/preconditions: ...
+- Rules/results: ...
+
+### UX states and copy
+- Happy: ...
+- Empty: ...
+- Loading/pending: ...
+- Error/failure: ...
+- Edge/constraint: ...
+- Key copy: ...
+
+### Technical shape
+- Boundaries/API/data flow: ...
+- Tradeoffs: ...
+
+### Scope and tradeoffs
+- In: ...
+- Out: ...
+- Tradeoffs: ...
+
+### Alternatives considered
+- Option A: ...
+- Option B/no-op: ...
+
+### Acceptance criteria
+- ...
+
+### Recommended next step
+Module and rationale
+```