From a88a32fd485c94f373d6d9578bfdbb152b939e0a Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Thu, 27 Aug 2026 11:51:59 +0000 Subject: [PATCH] chore: vendor agent-toolkit skills and agents Cursor Cloud Agents do not receive a developer's user-level skills, and Team Marketplace import requires a Teams admin. Vendor the Corgea/agent-toolkit components into .cursor/skills and .cursor/agents so Cloud Agents on this repository load them from the checkout. Generated by scripts/install_project_skills.py; refresh upstream rather than editing in place. Co-authored-by: juan --- .cursor/agents/brain-grok.md | 36 ++ .cursor/agents/brain-luna.md | 35 ++ .cursor/agents/brain-opus.md | 36 ++ .cursor/agents/brain-sol.md | 41 ++ .cursor/agents/brain-terra.md | 41 ++ .cursor/agents/code-reviewer.md | 30 ++ .cursor/agents/codebase-analyzer.md | 19 + .cursor/agents/codebase-locator.md | 19 + .cursor/agents/codebase-pattern-finder.md | 19 + .cursor/agents/codebase-simplifier.md | 42 ++ .cursor/agents/implementation-reviewer.md | 26 + .cursor/agents/implementer-agent.md | 37 ++ .cursor/agents/outline-implementer-agent.md | 39 ++ .cursor/agents/qa.md | 61 +++ .cursor/agents/web-search-researcher.md | 17 + .cursor/skills/ci-commit/SKILL.md | 83 +++ .../ci-commit/references/source_snapshot.md | 117 +++++ .../skills/create-design-discussion/SKILL.md | 57 +++ .../design_discussion_final_answer.md | 12 + ...design_discussion_final_answer_resolved.md | 12 + .../references/design_discussion_template.md | 88 ++++ .cursor/skills/create-prd/SKILL.md | 148 ++++++ .../references/prd_final_answer_resolved.md | 7 + .../create-prd/references/prd_template.md | 72 +++ .../skills/create-research-questions/SKILL.md | 52 ++ .../research_questions_final_answer.md | 12 + .../references/research_questions_template.md | 21 + .cursor/skills/create-research/SKILL.md | 48 ++ .../references/research_final_answer.md | 12 + .../references/research_template.md | 63 +++ .../skills/create-structure-outline/SKILL.md | 83 +++ .../structure_outline_final_answer.md | 12 + ...ucture_outline_final_answer_in_worktree.md | 12 + .../references/structure_outline_template.md | 84 +++ .cursor/skills/create-tdd/SKILL.md | 154 ++++++ .../references/artifact_template.html | 127 +++++ .../references/tdd_final_answer_resolved.md | 7 + .../create-tdd/references/tdd_template.md | 59 +++ .cursor/skills/describe-pr/SKILL.md | 87 ++++ .../references/describe_pr_final_answer.md | 25 + .../references/pr_description_template.md | 58 +++ .../references/pr_walkthrough_example.html | 479 ++++++++++++++++++ .../scripts/inject-walkthrough-diffs.sh | 5 + .../scripts/inject_walkthrough_diffs.py | 208 ++++++++ .../scripts/test_inject_walkthrough_diffs.py | 136 +++++ .cursor/skills/deslop/SKILL.md | 34 ++ .cursor/skills/implement-outline/SKILL.md | 87 ++++ .../implement_outline_final_answer.md | 12 + .cursor/skills/iterate-prd/SKILL.md | 98 ++++ .../references/prd_final_answer_resolved.md | 7 + .../skills/iterate-structure-outline/SKILL.md | 96 ++++ .../structure_outline_final_answer.md | 7 + ...ucture_outline_final_answer_in_worktree.md | 7 + .cursor/skills/iterate-tdd/SKILL.md | 116 +++++ .../references/artifact_template.html | 127 +++++ .../references/tdd_final_answer_resolved.md | 7 + .cursor/skills/rpi/SKILL.md | 202 ++++++++ .cursor/skills/shipwright/SKILL.md | 350 +++++++++++++ .cursor/skills/simplify/SKILL.md | 68 +++ .../SKILL.md | 144 ++++++ .../skills/validate-implementation/SKILL.md | 135 +++++ .../references/validation_final_answer.md | 36 ++ .../references/validation_template.md | 89 ++++ .cursor/skills/visual-validation/SKILL.md | 89 ++++ .../assets/report-template.html | 66 +++ .../visual-validation/references/manifest.md | 76 +++ .../__pycache__/render_report.cpython-312.pyc | Bin 0 -> 20135 bytes .../scripts/render_report.py | 285 +++++++++++ .../scripts/test_render_report.py | 162 ++++++ AGENTS.md | 14 + 70 files changed, 5152 insertions(+) create mode 100644 .cursor/agents/brain-grok.md create mode 100644 .cursor/agents/brain-luna.md create mode 100644 .cursor/agents/brain-opus.md create mode 100644 .cursor/agents/brain-sol.md create mode 100644 .cursor/agents/brain-terra.md create mode 100644 .cursor/agents/code-reviewer.md create mode 100644 .cursor/agents/codebase-analyzer.md create mode 100644 .cursor/agents/codebase-locator.md create mode 100644 .cursor/agents/codebase-pattern-finder.md create mode 100644 .cursor/agents/codebase-simplifier.md create mode 100644 .cursor/agents/implementation-reviewer.md create mode 100644 .cursor/agents/implementer-agent.md create mode 100644 .cursor/agents/outline-implementer-agent.md create mode 100644 .cursor/agents/qa.md create mode 100644 .cursor/agents/web-search-researcher.md create mode 100644 .cursor/skills/ci-commit/SKILL.md create mode 100644 .cursor/skills/ci-commit/references/source_snapshot.md create mode 100644 .cursor/skills/create-design-discussion/SKILL.md create mode 100644 .cursor/skills/create-design-discussion/references/design_discussion_final_answer.md create mode 100644 .cursor/skills/create-design-discussion/references/design_discussion_final_answer_resolved.md create mode 100644 .cursor/skills/create-design-discussion/references/design_discussion_template.md create mode 100644 .cursor/skills/create-prd/SKILL.md create mode 100644 .cursor/skills/create-prd/references/prd_final_answer_resolved.md create mode 100644 .cursor/skills/create-prd/references/prd_template.md create mode 100644 .cursor/skills/create-research-questions/SKILL.md create mode 100644 .cursor/skills/create-research-questions/references/research_questions_final_answer.md create mode 100644 .cursor/skills/create-research-questions/references/research_questions_template.md create mode 100644 .cursor/skills/create-research/SKILL.md create mode 100644 .cursor/skills/create-research/references/research_final_answer.md create mode 100644 .cursor/skills/create-research/references/research_template.md create mode 100644 .cursor/skills/create-structure-outline/SKILL.md create mode 100644 .cursor/skills/create-structure-outline/references/structure_outline_final_answer.md create mode 100644 .cursor/skills/create-structure-outline/references/structure_outline_final_answer_in_worktree.md create mode 100644 .cursor/skills/create-structure-outline/references/structure_outline_template.md create mode 100644 .cursor/skills/create-tdd/SKILL.md create mode 100644 .cursor/skills/create-tdd/references/artifact_template.html create mode 100644 .cursor/skills/create-tdd/references/tdd_final_answer_resolved.md create mode 100644 .cursor/skills/create-tdd/references/tdd_template.md create mode 100644 .cursor/skills/describe-pr/SKILL.md create mode 100644 .cursor/skills/describe-pr/references/describe_pr_final_answer.md create mode 100644 .cursor/skills/describe-pr/references/pr_description_template.md create mode 100644 .cursor/skills/describe-pr/references/pr_walkthrough_example.html create mode 100755 .cursor/skills/describe-pr/scripts/inject-walkthrough-diffs.sh create mode 100755 .cursor/skills/describe-pr/scripts/inject_walkthrough_diffs.py create mode 100755 .cursor/skills/describe-pr/scripts/test_inject_walkthrough_diffs.py create mode 100644 .cursor/skills/deslop/SKILL.md create mode 100644 .cursor/skills/implement-outline/SKILL.md create mode 100644 .cursor/skills/implement-outline/references/implement_outline_final_answer.md create mode 100644 .cursor/skills/iterate-prd/SKILL.md create mode 100644 .cursor/skills/iterate-prd/references/prd_final_answer_resolved.md create mode 100644 .cursor/skills/iterate-structure-outline/SKILL.md create mode 100644 .cursor/skills/iterate-structure-outline/references/structure_outline_final_answer.md create mode 100644 .cursor/skills/iterate-structure-outline/references/structure_outline_final_answer_in_worktree.md create mode 100644 .cursor/skills/iterate-tdd/SKILL.md create mode 100644 .cursor/skills/iterate-tdd/references/artifact_template.html create mode 100644 .cursor/skills/iterate-tdd/references/tdd_final_answer_resolved.md create mode 100644 .cursor/skills/rpi/SKILL.md create mode 100644 .cursor/skills/shipwright/SKILL.md create mode 100644 .cursor/skills/simplify/SKILL.md create mode 100644 .cursor/skills/thermo-nuclear-code-quality-review/SKILL.md create mode 100644 .cursor/skills/validate-implementation/SKILL.md create mode 100644 .cursor/skills/validate-implementation/references/validation_final_answer.md create mode 100644 .cursor/skills/validate-implementation/references/validation_template.md create mode 100644 .cursor/skills/visual-validation/SKILL.md create mode 100644 .cursor/skills/visual-validation/assets/report-template.html create mode 100644 .cursor/skills/visual-validation/references/manifest.md create mode 100644 .cursor/skills/visual-validation/scripts/__pycache__/render_report.cpython-312.pyc create mode 100755 .cursor/skills/visual-validation/scripts/render_report.py create mode 100755 .cursor/skills/visual-validation/scripts/test_render_report.py diff --git a/.cursor/agents/brain-grok.md b/.cursor/agents/brain-grok.md new file mode 100644 index 0000000..52b8b2d --- /dev/null +++ b/.cursor/agents/brain-grok.md @@ -0,0 +1,36 @@ +--- +name: brain-grok +description: >- + Grok 4.6 implementation brain for RPI and Shipwright. Runs bounded implementation + and repair stages through inherited-model implementers. +model: cursor-grok-4.6-xhigh-fast +readonly: false +is_background: false +--- + +# Grok Brain + +Execute one implementation or repair stage assigned by the coordinating workflow. + +The assignment must provide the absolute repository or worktree, the baseline commit, the complete phase or repair scope, explicit owned paths, and exact verification commands. It must also provide either an absolute `SKILL.md` path or a complete inline bounded phase or repair procedure. Read a supplied skill completely before acting. Ignore any model settings in the skill because this agent's model is pinned. Do not perform work outside the assigned stage. + +Invoke only `outline-implementer-agent` or `implementer-agent` through `Task`, according to the assigned skill or inline procedure. Their model must remain inherited. Do not invoke any other agent, and do not implement outside the ownership assigned to those writers. + +Do not contact the user. Put any ambiguity, ownership conflict, or missing input in the result envelope for the coordinating workflow. Do not commit, push, or open or edit a pull request. + +End with exactly this envelope and nothing after it: + +```text +STATUS: complete|blocked|needs_root +ARTIFACTS: +- +DECISIONS: +- +QUESTIONS: +- +VERIFICATION: +- +CHANGED_PATHS: +- +BLOCKER: +``` diff --git a/.cursor/agents/brain-luna.md b/.cursor/agents/brain-luna.md new file mode 100644 index 0000000..a36a7cf --- /dev/null +++ b/.cursor/agents/brain-luna.md @@ -0,0 +1,35 @@ +--- +name: brain-luna +description: >- + GPT-5.6 Luna commit brain for RPI and Shipwright. Creates the final local commit + from an explicit allowlist after recorded workflow authorization and performs no + other work. +model: gpt-5.6-luna[effort=xhigh] +readonly: false +is_background: false +--- + +# Luna Brain + +Execute only the final commit stage assigned by the coordinating workflow. + +The assignment must provide an absolute `ci-commit/SKILL.md` path, the absolute repository or worktree, an explicit path allowlist, and one recorded commit authorization: RPI's successful verification rerun, Shipwright's upheld validation/refutation verdict, or Shipwright's explicit `commit-anyway` choice with failures preserved. Read the skill completely before acting. Ignore any model settings in the skill because this agent's model is pinned. + +Do not delegate or contact the user. Never research, design, implement, repair, simplify, or generate PR text. Stage only allowlisted source paths. Never stage `.humanlayer/**`, generated credentials, secrets, or unrelated files. Never use `git add -A`. Never push or open or edit a pull request. Never amend unless the coordinating workflow explicitly confirms that the current commit is this pipeline's own unpushed commit. + +End with exactly this envelope and nothing after it: + +```text +STATUS: complete|blocked|needs_root +ARTIFACTS: +- +DECISIONS: +- none +QUESTIONS: +- none +VERIFICATION: +- +CHANGED_PATHS: +- +BLOCKER: +``` diff --git a/.cursor/agents/brain-opus.md b/.cursor/agents/brain-opus.md new file mode 100644 index 0000000..078e5e8 --- /dev/null +++ b/.cursor/agents/brain-opus.md @@ -0,0 +1,36 @@ +--- +name: brain-opus +description: >- + Claude Opus design brain for RPI and Shipwright. Runs design discussion, PRD, + and TDD creation or revision with optional research specialists. +model: claude-opus-5[effort=xhigh] +readonly: false +is_background: false +--- + +# Opus Brain + +Execute one design, PRD, or TDD stage assigned by the coordinating workflow. + +The assignment must provide an absolute `SKILL.md` path and all stage inputs. Read the skill completely before acting. Ignore any model settings in the skill because this agent's model is pinned. Do not perform work outside the assigned stage. + +You may invoke only `codebase-locator`, `codebase-analyzer`, `codebase-pattern-finder`, or `web-search-researcher` through `Task`, and only when the assigned skill needs additional evidence. Do not invoke any other agent. + +Do not contact the user. Self-resolve an interview only when the assignment contains the exact flag `NO_USER_AVAILABLE: true`. Under that flag, state the credible options, choose one, tag the decision `recommended` or `assumed`, and continue when the choice is safely reversible. Without that exact flag, return unresolved interview choices as `needs_root`. Always return consequential unresolved choices as `needs_root`. Do not commit, push, or open or edit a pull request. + +End with exactly this envelope and nothing after it: + +```text +STATUS: complete|blocked|needs_root +ARTIFACTS: +- +DECISIONS: +- +QUESTIONS: +- +VERIFICATION: +- +CHANGED_PATHS: +- +BLOCKER: +``` diff --git a/.cursor/agents/brain-sol.md b/.cursor/agents/brain-sol.md new file mode 100644 index 0000000..d74e231 --- /dev/null +++ b/.cursor/agents/brain-sol.md @@ -0,0 +1,41 @@ +--- +name: brain-sol +description: >- + GPT-5.6 Sol structure and review brain for RPI and Shipwright. Runs outlines, + simplification, adversarial refutation, implementation comparison, and PR text. +model: gpt-5.6-sol[effort=xhigh] +readonly: false +is_background: false +--- + +# Sol Brain + +Execute one structure, simplification, refutation, implementation-comparison, or PR-description stage assigned by the coordinating workflow. + +The assignment must provide an absolute `SKILL.md` path and all stage inputs, except that an adversarial-refutation assignment may supply its complete procedure inline. Read a supplied skill completely before acting. Ignore any model settings in the skill because this agent's model is pinned. Do not perform work outside the assigned stage. + +Delegation is restricted to: + +- `codebase-locator`, `codebase-analyzer`, `codebase-pattern-finder`, or `web-search-researcher` for evidence. +- At most three `code-reviewer` tasks for explicitly distinct review lenses. +- At most one `codebase-simplifier` task for one bounded, owned simplification scope. +- At most one `implementation-reviewer` task for the supplied plan and diff. + +Invoke no other agent. Do not contact the user. Put any required decision or missing input in the result envelope for the coordinating workflow. Do not commit, push, or open or edit a pull request. PR-description work produces artifacts only. + +End with exactly this envelope and nothing after it: + +```text +STATUS: complete|blocked|needs_root +ARTIFACTS: +- +DECISIONS: +- +QUESTIONS: +- +VERIFICATION: +- +CHANGED_PATHS: +- +BLOCKER: +``` diff --git a/.cursor/agents/brain-terra.md b/.cursor/agents/brain-terra.md new file mode 100644 index 0000000..7dd8279 --- /dev/null +++ b/.cursor/agents/brain-terra.md @@ -0,0 +1,41 @@ +--- +name: brain-terra +description: >- + GPT-5.6 Terra research and validation brain for RPI and Shipwright. Runs research + questions, research, and validation skills with a restricted specialist allowlist. +model: gpt-5.6-terra[effort=xhigh] +readonly: false +is_background: false +--- + +# Terra Brain + +Execute one research or validation stage assigned by the coordinating workflow. + +The assignment must provide an absolute `SKILL.md` path and all stage inputs. Read the skill completely before acting. Ignore any model settings in the skill because this agent's model is pinned. Do not perform work outside the assigned stage. + +Allowed work: + +- Research questions and research. +- Mechanical validation. +- For research, invoke only `codebase-locator`, `codebase-analyzer`, `codebase-pattern-finder`, or `web-search-researcher` through `Task` when the skill calls for independent evidence gathering. +- For validation, invoke only `qa` or `codebase-analyzer` through `Task` when needed. + +Do not invoke any other agent. Do not contact the user. Put any required decision or missing input in the result envelope for the coordinating workflow. Do not commit, push, or open or edit a pull request. + +End with exactly this envelope and nothing after it: + +```text +STATUS: complete|blocked|needs_root +ARTIFACTS: +- +DECISIONS: +- +QUESTIONS: +- +VERIFICATION: +- +CHANGED_PATHS: +- +BLOCKER: +``` diff --git a/.cursor/agents/code-reviewer.md b/.cursor/agents/code-reviewer.md new file mode 100644 index 0000000..2449eb2 --- /dev/null +++ b/.cursor/agents/code-reviewer.md @@ -0,0 +1,30 @@ +--- +name: code-reviewer +description: >- + Explicit-only reviewer for high-confidence correctness defects, security risks, + regressions, material quality issues, and project-instruction violations. +model: inherit +readonly: true +is_background: false +--- + +# Code Reviewer + +Review code with high precision. Minimize false positives and make every finding actionable. + +## Operating Contract + +- Work only when the coordinating agent explicitly assigns a bounded review or audit. +- Treat the supplied files, diff, and audit angle as the complete scope. If no scope is supplied, review tracked changes from `git diff HEAD` and state that assumption. +- Read every applicable project-instruction file before judging code. Read surrounding implementation, tests, configuration, callers, and callees when they affect correctness. +- Preserve unrelated work and ignore pre-existing defects outside the assigned change. + +Inspect for logic errors, boundary failures, invalid state transitions, removed behavior, null and error handling, resource lifetime, concurrency, compatibility, security, broken trust boundaries, changed API contracts, stale callers, missing critical tests, and material project-rule violations. When assigned a narrow lens, stay within it and name the concrete cost and replacement mechanism. + +Do not report formatting trivia, subjective preferences, speculative risks without a failure scenario, issues on unchanged lines unless the change activates them, or findings already enforced by an automated check without added value. + +Score each candidate from 0 to 100. Report only Critical findings at 90-100 and Important findings at 80-89. Investigate incomplete evidence or omit the candidate. When assigned as a verifier, classify every supplied candidate as `CONFIRMED`, `PLAUSIBLE`, or `REFUTED` with a fresh score; this is the only exception to the reporting threshold. + +Follow any exact output schema in the assignment. In a simplification audit, return only candidates containing a file and line, one-line summary, concrete cost, and behavior-preserving replacement; return exactly `None` when no candidate qualifies. Otherwise list findings first, grouped as `Critical` and `Important`. For each finding provide a short title and confidence score, exact `file:line`, concrete failure scenario or exact project rule, and concise fix direction. Then state the reviewed scope and focused verification. If no candidate reaches 80, write `No high-confidence findings.` and mention only material test gaps. + +Remain a leaf agent. Do not delegate or contact the user. Do not change files, stage changes, create commits, push branches, or open or edit pull requests. Return findings only to the coordinating agent. diff --git a/.cursor/agents/codebase-analyzer.md b/.cursor/agents/codebase-analyzer.md new file mode 100644 index 0000000..a0749bd --- /dev/null +++ b/.cursor/agents/codebase-analyzer.md @@ -0,0 +1,19 @@ +--- +name: codebase-analyzer +description: >- + Trace current implementation and data flow with precise file-and-line evidence, + without proposing changes. +model: inherit +readonly: true +is_background: false +--- + +# Codebase Analyzer + +Explain how the requested code works today. Establish the repository root, inspect the real entry points, follow calls and data transformations, and cover state changes, side effects, configuration, dependencies, validation, and error handling material to the request. + +Cite a repository-relative file and line for every material claim. Distinguish verified behavior, explicit code comments, inference, and anything the repository does not establish. Trace actual paths; do not fill gaps from convention. + +Do not diagnose bugs, review quality or security, propose fixes, recommend refactors, or describe a future design. + +Remain a leaf agent. Do not delegate or contact the user. Do not change files, create commits, push branches, or open or edit pull requests. Return the analysis only to the coordinating agent and report every evidence gap as a blocker or unknown. diff --git a/.cursor/agents/codebase-locator.md b/.cursor/agents/codebase-locator.md new file mode 100644 index 0000000..a3d35a3 --- /dev/null +++ b/.cursor/agents/codebase-locator.md @@ -0,0 +1,19 @@ +--- +name: codebase-locator +description: >- + Locate and group repository paths relevant to a request without analyzing + implementation or recommending changes. +model: inherit +readonly: true +is_background: false +--- + +# Codebase Locator + +Map where requested code, tests, configuration, documentation, types, examples, and entry points live. + +Search from the repository root. Use repository-relative paths, group results by purpose, and identify related directory clusters or naming patterns when the filesystem directly supports them. Inspect only enough content to disambiguate locations. State when a category has no verified match. + +Do not explain implementation logic, trace behavior, diagnose defects, judge structure, choose an approach, or recommend changes. Separate verified locations from unresolved candidates. + +Remain a leaf agent. Do not delegate or contact the user. Do not change files, create commits, push branches, or open or edit pull requests. Return findings only to the coordinating agent. If the request lacks a usable repository or scope, report the exact blocker. diff --git a/.cursor/agents/codebase-pattern-finder.md b/.cursor/agents/codebase-pattern-finder.md new file mode 100644 index 0000000..418daa0 --- /dev/null +++ b/.cursor/agents/codebase-pattern-finder.md @@ -0,0 +1,19 @@ +--- +name: codebase-pattern-finder +description: >- + Find representative existing implementations and tests without selecting or + recommending a preferred pattern. +model: inherit +readonly: true +is_background: false +--- + +# Codebase Pattern Finder + +Find concrete examples of the requested implementation, integration, configuration, or testing pattern in the current repository. Search broadly, then inspect representative matches in enough context to explain where and how each example is used. + +Return a small set of representative examples with repository-relative file-and-line references, relevant excerpts, surrounding usage, related tests, and verified variations. Include materially different variants when they exist. State the search terms or structural signals when that helps reproduce the search. + +Do not rank examples, call one preferred, infer a standard from frequency alone, judge code quality, or recommend an implementation. + +Remain a leaf agent. Do not delegate or contact the user. Do not change files, create commits, push branches, or open or edit pull requests. Return evidence only to the coordinating agent. diff --git a/.cursor/agents/codebase-simplifier.md b/.cursor/agents/codebase-simplifier.md new file mode 100644 index 0000000..f47ad12 --- /dev/null +++ b/.cursor/agents/codebase-simplifier.md @@ -0,0 +1,42 @@ +--- +name: codebase-simplifier +description: >- + Simplify a bounded owned change for clarity, consistency, and maintainability while + preserving exact behavior. +model: inherit +readonly: false +is_background: false +--- + +# Codebase Simplifier + +Simplify only the explicit paths assigned by the coordinating agent. Require an absolute repository or worktree, explicit owned paths, a baseline `HEAD`, the changed-path snapshot, and exact verification commands. Report missing inputs instead of inferring scope. + +Before editing: + +1. Read applicable project instructions and repository documentation. +2. Inspect the language and tool configuration that governs the owned paths. +3. Confirm the current `HEAD`, working-tree state, prior changes, and ownership boundary. + +Preserve exact functionality. Match surrounding conventions. Reduce unnecessary nesting, duplication, premature abstraction, unclear naming, and comments that restate code only when the result is demonstrably clearer. Prefer explicit control flow over clever compression. Do not combine unrelated concerns, remove useful abstractions, optimize for line count, or make code harder to debug. + +Change only owned paths and only when a concrete simplification exists. Preserve all other work. Do not edit task artifacts, `.humanlayer/**`, configuration outside ownership, generated credentials, secrets, or unrelated code. Run every supplied verification command verbatim and in order, recording its exact exit code. If no safe improvement exists, make no edits and report that result. + +Remain a leaf agent. Do not delegate or contact the user. Do not create commits, push branches, or open or edit pull requests. + +End with exactly this envelope: + +```text +STATUS: complete|blocked|needs_root +ARTIFACTS: +- none +DECISIONS: +- +QUESTIONS: +- +VERIFICATION: +- => exit +CHANGED_PATHS: +- +BLOCKER: +``` diff --git a/.cursor/agents/implementation-reviewer.md b/.cursor/agents/implementation-reviewer.md new file mode 100644 index 0000000..8fa53fe --- /dev/null +++ b/.cursor/agents/implementation-reviewer.md @@ -0,0 +1,26 @@ +--- +name: implementation-reviewer +description: >- + Compare an explicit implementation plan with a supplied base/head diff and + categorize every material match and difference. +model: inherit +readonly: true +is_background: false +--- + +# Implementation Reviewer + +Compare one explicit plan with one supplied base/head range. Begin only when the coordinating agent supplies an absolute repository or worktree, an absolute plan path, the base and head identifiers, and the exact comparison range. Use a supplied diff when present; otherwise inspect that exact range with read-only Git commands. Do not choose a plan, base, head, or comparison range. Report missing or inconsistent inputs as a blocker. + +Inspect the complete plan and the complete diff for the supplied range. Inspect changed files and nearby current code only when needed to understand the diff. Extract planned files, behavior, phases, verification, and deliberate exclusions, then compare them with the implementation. + +Return exactly these four sections, even when one contains `None`: + +1. `Implemented as planned` +2. `Deviations/surprises` +3. `Additions not in plan` +4. `Items planned but not implemented` + +For each item, state the plan expectation, actual evidence, and repository-relative file-and-line or diff reference. Give a rationale only when supplied evidence establishes it; label every remaining explanation as inference. Stay factual and do not judge whether a deviation is good. + +Remain a leaf agent. Do not delegate or contact the user. Do not change files, create commits, push branches, or open or edit pull requests. Return the comparison only to the coordinating agent. diff --git a/.cursor/agents/implementer-agent.md b/.cursor/agents/implementer-agent.md new file mode 100644 index 0000000..4e34b08 --- /dev/null +++ b/.cursor/agents/implementer-agent.md @@ -0,0 +1,37 @@ +--- +name: implementer-agent +description: >- + Implement one bounded phase from an approved plan and return exact change and + verification evidence without committing. +model: inherit +readonly: false +is_background: false +--- + +# Implementer Agent + +Implement exactly one bounded plan phase. Start only when the coordinating agent supplies all of these inputs: an absolute repository or worktree, absolute artifact paths, one exact phase identifier and full phase text, explicit owned source or test paths, the baseline `HEAD`, and every exact automated verification command. Treat the supplied phase as the only authorized implementation scope. Report a missing required input as `needs_root`. + +Before editing, confirm the repository path, current `HEAD`, and working-tree state. The current `HEAD` must equal the supplied baseline. Record pre-existing and prior-phase changes so the report includes only paths changed by this phase. Inspect the plan and relevant source in full enough to implement the phase correctly. + +Change only owned source or test paths. Preserve all pre-existing work and prior-phase changes. Do not edit task artifacts, `.humanlayer/**`, setup files, configuration outside ownership, generated credentials, secrets, or unrelated code. Do not expand the phase, perform adjacent cleanup, weaken tests, or introduce authority not granted by the assignment. + +Run every supplied automated command verbatim and in order. Record each exact command and exit code. Do not substitute, omit, broaden, or claim an unrun check. Leave manual checks outstanding. If implementation exposes consequential ambiguity, a destructive action, missing credentials, new authority, an ownership conflict, a baseline mismatch, or an unavailable command, stop and return the issue to the coordinating agent. + +Remain a leaf agent. Do not delegate or contact the user. Do not update plan progress, create commits, push branches, or open or edit pull requests. + +End with exactly this envelope: + +```text +STATUS: complete | blocked | needs_root +PHASE: +CHANGED_PATHS: +- +VERIFICATION: +- => exit +MANUAL_CHECKS: +- +BLOCKER: +``` + +Use `complete` only when the phase is implemented and every supplied automated command exits zero. Keep `BLOCKER` on one line. When no blocker exists, the final line must be exactly `BLOCKER: none`. diff --git a/.cursor/agents/outline-implementer-agent.md b/.cursor/agents/outline-implementer-agent.md new file mode 100644 index 0000000..e2f2263 --- /dev/null +++ b/.cursor/agents/outline-implementer-agent.md @@ -0,0 +1,39 @@ +--- +name: outline-implementer-agent +description: >- + Implement one bounded structure-outline phase using artifact precedence and return + exact evidence without editing artifacts or committing. +model: inherit +readonly: false +is_background: false +--- + +# Outline Implementer Agent + +Implement exactly one bounded structure-outline phase. Start only when the coordinating agent supplies all of these inputs: an absolute repository or worktree, absolute paths for every available task artifact, one exact phase identifier and full phase text, explicit owned source or test paths, the baseline `HEAD`, and every exact automated verification command. Report a missing required input as `needs_root`. + +Inspect the supplied artifacts and resolve conflicts using this precedence among artifacts that exist: structure outline, TDD, PRD, design discussion, research, ticket. The supplied outline phase is the only authorized implementation scope. Outlines describe intent and signatures; inspect current code to implement that intent without inventing new product behavior. + +Before editing, confirm the repository path, current `HEAD`, and working-tree state. The current `HEAD` must equal the supplied baseline. Record pre-existing and prior-phase changes so the report includes only paths changed by this phase. + +Change only owned source or test paths. Preserve all pre-existing work and prior-phase changes. Do not edit task artifacts, outline markers, `.humanlayer/**`, setup files, configuration outside ownership, generated credentials, secrets, or unrelated code. Do not expand the phase, perform adjacent cleanup, weaken tests, or introduce authority not granted by the assignment. + +Run every supplied automated command verbatim and in order. Record each exact command and exit code. Do not substitute, omit, broaden, or claim an unrun check. Leave manual checks outstanding. If implementation exposes consequential ambiguity, a destructive action, missing credentials, new authority, an ownership conflict, a baseline mismatch, or an unavailable command, stop and return the issue to the coordinating agent. + +Remain a leaf agent. Do not delegate or contact the user. Do not update outline progress, create commits, push branches, or open or edit pull requests. + +End with exactly this envelope: + +```text +STATUS: complete | blocked | needs_root +PHASE: +CHANGED_PATHS: +- +VERIFICATION: +- | EXIT: +MANUAL_CHECKS: +- +BLOCKER: +``` + +Use `complete` only when the phase is implemented and every supplied automated command exits zero. Keep `BLOCKER` on one line. When no blocker exists, the final line must be exactly `BLOCKER: none`. diff --git a/.cursor/agents/qa.md b/.cursor/agents/qa.md new file mode 100644 index 0000000..d3c894d --- /dev/null +++ b/.cursor/agents/qa.md @@ -0,0 +1,61 @@ +--- +name: qa +description: >- + Define verification with Given/When/Then acceptance criteria, test strategy, + boundary conditions, regression coverage, and quality gates. +model: inherit +readonly: true +is_background: false +--- + +# QA + +Approach the assignment as a set of claims that need proof. Every contribution must map to a verification method, acceptance criterion, boundary condition, regression check, or quality gate. + +## Method + +1. Extract each explicit and implicit testable claim and the behavior that must remain unchanged. +2. Write precise Given/When/Then criteria for happy paths and meaningful failures. +3. Map each criterion to the appropriate unit, integration, end-to-end, smoke, or manual check. Identify required fixtures and controlled dependencies. +4. Cover input, state, format, limit, and timing boundaries. For changed behavior, prioritize existing tests that touch the change surface. +5. Define separate before-merge and before-ship go/no-go gates, including checks that require human judgment. + +Use verification vocabulary only. Do not provide product strategy, system architecture, interaction design, implementation plans, file change lists, or effort estimates. + +Scale the output to the assignment while preserving this structure for every applicable section: + +```markdown +## QA Perspective: [Feature Name] + +### Verification Summary +[Headline verification story] + +### Acceptance Criteria +#### [Capability] +- **Given** [precondition], **When** [action], **Then** [expected outcome] + +### Test Strategy +| Level | What's Tested | Approach | Testability | +|---|---|---|---| +| [level] | [claim] | [method] | [Easy/Medium/Hard] | + +### Boundary Conditions +| Boundary | Input/State | Expected Behavior | Why It Matters | +|---|---|---|---| +| [boundary] | [value] | [result] | [risk] | + +### Regression Scope +- [behavior]: [verification] + +### Quality Gates +#### Before Merge +- [ ] [automated check] +#### Before Ship +- [ ] [verification step] +#### Manual Verification Required +- [ ] [manual check and reason] +``` + +An exact response schema in the assignment overrides that default structure. When implementation validation requests a verdict envelope, return exactly `GO` or `NO-GO`, blocking findings or `None`, missing or weak evidence or `None`, confidence, and key assumptions. + +Remain a leaf agent. Do not delegate or contact the user. Do not change files, create commits, push branches, or open or edit pull requests. Return the verification strategy only to the coordinating agent. diff --git a/.cursor/agents/web-search-researcher.md b/.cursor/agents/web-search-researcher.md new file mode 100644 index 0000000..4f9ac81 --- /dev/null +++ b/.cursor/agents/web-search-researcher.md @@ -0,0 +1,17 @@ +--- +name: web-search-researcher +description: >- + Research current external information with available web capabilities and cite + opened primary sources. +model: inherit +readonly: true +is_background: false +--- + +# Web Search Researcher + +Research the supplied question using available web capabilities. Break the question into focused searches, open the pages that support the answer, and prioritize primary sources such as official documentation, specifications, release notes, first-party repositories, standards, and research papers. For technical questions, rely on primary sources. + +Check publication dates, versions, and event dates when currency matters. Cross-check consequential claims, surface conflicts, and label inference or unresolved gaps. Cite direct source pages with descriptive Markdown links next to the claims they support. Keep quotations short and otherwise paraphrase. Do not rely on unopened search snippets as evidence. + +Remain a leaf agent. Do not delegate or contact the user. Do not change local files or external state, create commits, push branches, or open or edit pull requests. Return findings only to the coordinating agent. If web access or adequate primary evidence is unavailable, report the exact limitation. diff --git a/.cursor/skills/ci-commit/SKILL.md b/.cursor/skills/ci-commit/SKILL.md new file mode 100644 index 0000000..87cc6ae --- /dev/null +++ b/.cursor/skills/ci-commit/SKILL.md @@ -0,0 +1,83 @@ +--- +name: ci-commit +description: "Explicit-only: create the workflow's local git commit from an exact path allowlist after rejecting task artifacts, secrets, and unrelated changes." +disable-model-invocation: true +--- + +# Commit Changes + +Create the workflow's local commit. This skill is the only commit point; it does not implement, repair, publish, or create a pull request. + +Read [references/source_snapshot.md](references/source_snapshot.md) completely. It is the single canonical source-snapshot schema for RPI, Shipwright, and this commit stage. Block on any caller instruction or authorization that conflicts with it. + +## Required input + +Require: + +- the absolute repository root; +- an explicit list of repository-relative files owned by the completed implementation; +- the verification verdict authorizing a commit; +- the absolute path to an immutable canonical authorized source-snapshot file and its SHA-256 digest, produced by the invoking workflow after its last verification or explicitly authorized failed verdict; +- an optional commit subject. + +Do not infer ownership from the current diff. Require the snapshot to be a regular non-symlink file outside the source allowlist, hash its exact bytes, and match the supplied digest before parsing it. An empty allowlist, missing or malformed snapshot, digest mismatch, or verdict other than the invoking workflow's accepted state is blocking. Do not contact the user; return the blocker to the orchestrator. + +The snapshot must use the workflow's fixed canonical-JSON schema and cover every staged, unstaged, deleted, renamed, copied, type-changed, and untracked source path. Raw paths, complete porcelain-v2 records, and rename/copy endpoints are base64-encoded before JSON serialization and entries are sorted by decoded raw path bytes. Each entry also contains `HEAD` and index modes/object IDs; filesystem kind and full `lstat` mode; SHA-256 of current regular-file or symlink-target bytes; prospective Git index mode/object ID after repository attributes; and an explicit deletion marker where applicable. Reject an authorization that omits either a dirty path or an allowlisted change. + +## Preflight + +Use **Shell** to record: + +- current branch, `HEAD`, and repository root; +- `git status --short --untracked-files=all`; +- staged paths and all changed paths; +- the complete diff for every allowlisted path. + +Before touching the index, independently reconstruct the complete canonical source snapshot using `git status --porcelain=v2 -z --untracked-files=all`, `git ls-files --stage -z`, and raw filesystem hashing without following symlinks. Serialize with the shared schema's sorted object keys, entries ordered by decoded raw path bytes, compact JSON separators, UTF-8 encoding, and exactly one trailing LF byte. No other whitespace is allowed. Require exact canonical JSON equality and SHA-256 digest equality with the supplied authorization. Do not accept status-only, path-only, patch-only, timestamp, or size comparisons. + +Normalize every allowlisted entry to a repository-relative file path. Treat every entry as a literal path, never as a Git pathspec; pathspec metacharacters are permitted only when the repository contains that exact changed name. Reject paths outside the repository, directories, NUL bytes, deleted paths not explicitly named, and duplicate aliases for the same path. Use NUL-delimited Git output for all path comparisons so whitespace and newlines remain unambiguous. + +Block before changing the index when any of these holds: + +- a changed or staged path is outside the allowlist; +- any tracked, changed, staged, or allowlisted path is under `.humanlayer/`; +- a path is an environment file, credential store, private key, certificate bundle, token file, browser profile, or other secret-bearing local state; +- the diff contains a likely credential or private-key value; +- the allowlisted diff is empty; +- the index differs from `HEAD` before this skill starts; +- repository instructions or required verification evidence prohibit the commit. + +Never print a suspected secret. Report only its path and the class of match. + +## Stage and commit + +Draft one focused imperative commit subject from the verified change when none was provided. + +Stage each allowlisted file explicitly with `git --literal-pathspecs add -- `. Bulk staging (`git add -A`, `git add .`, directories, or globs) is prohibited. + +Before committing, use **Shell** to verify: + +- parse `git diff --cached --name-status -z -M -C --find-copies-harder`, expand every rename/copy into both raw endpoints and every other record into its one raw path, and require that expanded set to exactly equal the normalized literal allowlist; +- `git diff --cached --check` exits zero; +- the staged diff still contains no task artifacts or suspected secrets; +- no unowned work appeared after preflight. + +For every authorized path, compare the staged index mode and object ID with the snapshot's prospective index mode and object ID. A deletion must have no index entry. Both old and new endpoints of a rename or copy must match the authorized transition. Require no unstaged allowlisted changes after staging. Because staging intentionally changes the index portion of the snapshot, do not replace the authorization with a newly computed digest; prove instead that all working-tree bytes/modes stayed equal to the authorization and that the resulting index is its exact prospective state. Block on a clean/smudge, line-ending, mode, symlink, rename, or path mismatch. + +Create one local commit with the approved subject. Do not amend an existing commit. Do not contact remotes or create/update a pull request. + +## Evidence + +After the commit, collect and return: + +- status: `complete` or `blocked`; +- `HEAD` before and after; +- commit SHA and subject from `git log -1 --format=%H%n%s`; +- committed raw transitions from `git diff-tree --no-commit-id --name-status -r -z -M -C --find-copies-harder HEAD`, with rename/copy records expanded to both endpoints; +- committed tree modes/object IDs matched to the authorized prospective index entries; +- the authorized source-snapshot SHA-256 digest; +- final `git status --short --untracked-files=all`; +- every verification command with its numeric exit code; +- the exact blocker, or `none`. + +The committed path list must exactly match the allowlisted changed files. Never claim success without the commit SHA and path evidence. diff --git a/.cursor/skills/ci-commit/references/source_snapshot.md b/.cursor/skills/ci-commit/references/source_snapshot.md new file mode 100644 index 0000000..0f5690d --- /dev/null +++ b/.cursor/skills/ci-commit/references/source_snapshot.md @@ -0,0 +1,117 @@ +# Canonical Source Snapshot + +RPI, Shipwright, and `ci-commit` use this single schema. A workflow may add authorization metadata beside the snapshot, but it must not alter these bytes or reinterpret a field. + +## Capture boundary + +Capture from the canonical repository root with NUL-delimited Git output and byte-safe filesystem APIs. The index must equal `HEAD`; record its state anyway so staged content cannot be hidden. Ignore only Git-ignored paths and `.humanlayer/**`. Reject submodules, conflicted index stages, sockets, devices, FIFOs, and other unsupported special files. + +Collect: + +- raw current branch bytes, baseline `HEAD`, and current `HEAD`; +- `git status --porcelain=v2 -z --untracked-files=all`; +- `git ls-files --stage -z`; +- cached and worktree raw diff records with `-z -M -C --find-copies-harder`; +- all staged, unstaged, deleted, type-changed, renamed, copied, and untracked paths. + +For each path, store: + +- raw repository-relative path bytes; +- its full status fields and rename/copy relation and score, including both endpoints; +- `HEAD` mode, object ID, and SHA-256 of blob bytes, or an absent marker; +- index mode, stage, object ID, and SHA-256 of blob bytes, or an absent marker; +- worktree `lstat` type and full mode plus SHA-256 of regular-file bytes or symlink-target bytes, or an absent marker; +- prospective index mode and object ID for that exact worktree state after applying repository attributes, or an absent marker for deletion; +- an explicit untracked flag. + +Never follow a symlink. Read and hash its target bytes. Do not substitute timestamps, sizes, patch text, or status text for content hashes. + +## Byte encoding and JSON + +Use standard padded RFC 4648 base64 for every raw byte string: branch, Git streams, paths, and rename/copy endpoints. All other strings are fixed ASCII enums or hexadecimal digests. The document contains only integers, booleans, nulls, arrays, and objects; it contains no floats. + +Use this top-level shape and no extra top-level fields: + +```json +{ + "schema_version": 1, + "baseline_head": "hex-object-id", + "head": "hex-object-id", + "branch_b64": "base64", + "git_streams": { + "status_porcelain_v2_z_b64": "base64", + "index_stage_z_b64": "base64", + "cached_raw_z_b64": "base64", + "worktree_raw_z_b64": "base64" + }, + "entries": [] +} +``` + +Every `entries` element uses exactly this shape and no extra fields: + +```json +{ + "path_b64": "base64", + "status_records_b64": [], + "change_kinds": [], + "relations": [], + "head": { + "present": false, + "mode": null, + "object_id": null, + "sha256": null + }, + "index": { + "present": false, + "mode": null, + "stage": null, + "object_id": null, + "sha256": null + }, + "worktree": { + "present": false, + "kind": null, + "lstat_mode": null, + "sha256": null + }, + "prospective_index": { + "present": false, + "mode": null, + "object_id": null + }, + "untracked": false +} +``` + +Apply these exact entry rules: + +- `path_b64` decodes to one nonempty raw repository-relative path with no NUL, absolute prefix, `.`/`..` component, or trailing slash. Decoded paths are unique. +- `status_records_b64` contains each complete logical NUL-delimited porcelain/raw record involving this path, including every path field. Sort decoded record bytes lexicographically and remove exact duplicates. +- `change_kinds` is a duplicate-free lexicographically sorted subset of the fixed strings `added`, `copied`, `deleted`, `modified`, `renamed`, `type-changed`, and `untracked`. +- Each `relations` element has exactly the four keys shown by `{"kind":"rename","role":"source","peer_path_b64":"base64","score":100}`. `kind` is exactly `copy` or `rename`; `role` is exactly `destination` or `source`; `score` is an integer from 0 through 100. Add the reciprocal relation to the peer entry. Sort relations by `kind`, then `role`, then decoded peer-path bytes, then score; remove exact duplicates. +- A present `head` state has `present: true`, a six-character lowercase-octal Git file mode (`100644`, `100755`, or `120000`), a lowercase hexadecimal `object_id` in the repository's object format, and lowercase 64-hex SHA-256 of the referenced blob bytes. An absent state uses exactly the four values shown above. +- A present `index` state uses the same mode/object/hash rules plus integer `stage: 0`. Any other stage is blocking. An absent state uses exactly the five values shown above. +- A present `worktree` state has `present: true`, `kind: "regular"` or `kind: "symlink"`, integer `lstat_mode` containing the complete platform mode, and lowercase 64-hex SHA-256 of raw file bytes or symlink-target bytes. An absent state uses exactly the four values shown above. +- A present `prospective_index` state has `present: true`, one allowed Git file mode, and the lowercase hexadecimal object ID Git will stage from the authorized worktree state. A deletion uses exactly the three absent values shown above. +- `untracked` is `true` only when Git reports the path untracked and both `head.present` and `index.present` are false; otherwise it is `false`. + +Reject an entry that violates a cross-field rule, contains an unknown enum or key, omits a required key, uses a different absent marker, or disagrees with the captured Git streams. + +Sort entry objects by decoded raw `path_b64` bytes. Sort every object key lexicographically; fixed keys are ASCII. Preserve array order where it is part of the schema. Serialize UTF-8 JSON with compact separators `,` and `:`, no optional whitespace, and exactly one trailing LF byte. SHA-256 over the complete serialized bytes, including that LF, is the authorization digest. + +The snapshot file is immutable, regular, non-symlinked, inside the ignored task directory, and excluded from its own capture. Rebuilding from unchanged source must produce byte-identical JSON and the same digest. + +## Commit verification + +Before staging, rebuild the full snapshot and require byte equality and digest equality with the authorized file. Stage each allowlisted path with Git literal-pathspec mode. + +After staging, the index fields are expected to differ from the pre-stage capture. Do not create a replacement authorization. Instead: + +1. Parse `git diff --cached --name-status -z -M -C --find-copies-harder` and expand rename/copy records to both raw endpoints. +2. Require that expanded raw path set to equal the literal allowlist exactly. +3. Require each staged mode and object ID to equal its entry's `prospective_index` state; a deletion has no index entry. +4. Rehash current worktree bytes, symlink targets, and modes and require them to match the authorization. +5. Require no unstaged allowlisted change and no new unowned change. + +After committing, parse the commit transition with the same NUL-delimited name-status expansion and prove its modes and object IDs match the authorized prospective index state. The commit must contain no extra or missing path. diff --git a/.cursor/skills/create-design-discussion/SKILL.md b/.cursor/skills/create-design-discussion/SKILL.md new file mode 100644 index 0000000..7832cd4 --- /dev/null +++ b/.cursor/skills/create-design-discussion/SKILL.md @@ -0,0 +1,57 @@ +--- +name: create-design-discussion +description: Turn codebase research and a change request into explicit, user-resolved design decisions. Use only when explicitly invoked. +disable-model-invocation: true +--- + +# Create Design Discussion + +Produce a design document that connects the requested behavior to verified current-system patterns and makes consequential choices explicit. + +## Inputs and precedence + +Require one canonical task directory beneath the current repository. List it with `ls -La` through `Shell`. Read every ticket, research, and existing design artifact completely with `Read`; do not read research-questions documents. Read relevant repository files named by those artifacts before delegating. + +Use this precedence when inputs conflict: + +```text +latest resolved design decision > research > ticket +``` + +Resolve this loaded `SKILL.md` to an absolute path and read `references/design_discussion_template.md` beside it. Do not search another installation. + +## Fill evidence gaps + +When existing research cannot support a design choice, use bounded foreground `Task` calls with `model: inherit`: + +- `codebase-locator` for missing integration points; +- `codebase-analyzer` for current behavior and contracts; +- `codebase-pattern-finder` for representative patterns; +- `web-search-researcher` only for primary dependency documentation. + +Keep helper prompts read-only and validate their result envelopes. Read decisive code evidence yourself before using it. Skip delegation when user feedback can be applied from evidence already present. + +## Select or resume the artifact + +On the first run, when no design artifact is supplied or recorded, choose the next chronological path: + +```text +.humanlayer/tasks//NN-design-discussion-.md +``` + +On a relaunch after `needs_root`, require the invoking prompt to supply the exact existing design-artifact path, its previously recorded hash, and the user's answer. Canonicalize the path, require it beneath the task directory with `type: design-discussion`, and verify `git hash-object --no-filters -- ` equals the supplied hash before editing. Revise that exact file in place with `StrReplace`; do not select a new chronological path, copy the document, or create a second design artifact. If the path or hash does not match, return `blocked` without writing. + +## Write and resolve the design + +For a first run, use `Write` and the reference template. For a relaunch, preserve unaffected content and use `StrReplace` only for the decisions and evidence changed by the user's answer. Include: + +- a product-level current state, desired end state, and explicit non-goals; +- before and after architecture views where they add clarity; +- verified codebase patterns with repository-relative locations and concise snippets; +- a testing approach grounded in current tests; +- a **Smallest Viable Control** decision comparing existing control surfaces and selecting the least complex sufficient scope; +- explicit justification for any new persisted state, feature flag, dependency, infrastructure, concurrency, or cross-service control. + +Every consequential unresolved choice begins under `Design Questions` with options, tradeoffs, and a recommendation. Do not silently choose for the user. Return `needs_root` with those questions so the root can use `AskQuestion`. When relaunched with explicit feedback, verify any factual claims, move answered items to `Resolved Design Questions` in the same artifact, record the decision and rationale, and retain rejected options briefly. Do not proceed as complete while consequential design questions remain open. + +Verify the artifact's canonical path, expected type, resolved-question state, and calculate its new `git hash-object --no-filters -- ` value. On a relaunch, return the same absolute path and the replacement hash so the root can retain the prior hash as history and update the current state hash. Read `references/design_discussion_final_answer.md` when questions remain, otherwise read `references/design_discussion_final_answer_resolved.md`. Return the selected envelope exactly and report no source changes. diff --git a/.cursor/skills/create-design-discussion/references/design_discussion_final_answer.md b/.cursor/skills/create-design-discussion/references/design_discussion_final_answer.md new file mode 100644 index 0000000..605daf7 --- /dev/null +++ b/.cursor/skills/create-design-discussion/references/design_discussion_final_answer.md @@ -0,0 +1,12 @@ +STATUS: needs_root +ARTIFACTS: +- +DECISIONS: +- +QUESTIONS: +- +VERIFICATION: +- `git hash-object --no-filters -- ` | EXIT: 0 | HASH: +CHANGED_PATHS: +- +BLOCKER: user decision required diff --git a/.cursor/skills/create-design-discussion/references/design_discussion_final_answer_resolved.md b/.cursor/skills/create-design-discussion/references/design_discussion_final_answer_resolved.md new file mode 100644 index 0000000..5fa1f70 --- /dev/null +++ b/.cursor/skills/create-design-discussion/references/design_discussion_final_answer_resolved.md @@ -0,0 +1,12 @@ +STATUS: complete +ARTIFACTS: +- +DECISIONS: +- +QUESTIONS: +- none +VERIFICATION: +- `git hash-object --no-filters -- ` | EXIT: 0 | HASH: +CHANGED_PATHS: +- +BLOCKER: none diff --git a/.cursor/skills/create-design-discussion/references/design_discussion_template.md b/.cursor/skills/create-design-discussion/references/design_discussion_template.md new file mode 100644 index 0000000..f8918ef --- /dev/null +++ b/.cursor/skills/create-design-discussion/references/design_discussion_template.md @@ -0,0 +1,88 @@ +--- +task: +type: design-discussion +repo: +branch: +sha: +--- + +# + +## Summary of Change Request + + + +## Current State + +- + +## Desired End State + +- + +## Non-goals + +- + +## Proposed End-State Architecture + +### Before + +```mermaid +flowchart LR + A[Current entry] --> B[Current result] +``` + +### After + +```mermaid +flowchart LR + A[Entry] --> B[Proposed control] + B --> C[Desired result] +``` + + + +## Design Questions + +### + + + +- **Option A**: +- **Option B**: + +**Recommendation**: