From d3cd6f662c144865d5ea78fccd41547476969522 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 27 Sep 2026 20:06:20 +0000 Subject: [PATCH 1/2] argos-dev: add grilling, domain-modeling, wayfinder, research, prototype skills Adapted from upstream mattpocock/skills to workspace paths (docs/CONTEXT.md, docs/adr/, docs/research/, repos/argos/). grill-with-docs now composes grilling + domain-modeling. CLAUDE.md workflow mentions /wayfinder. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01818NEiW3BJCTrVCTDgaYDf --- .../.claude/skills/domain-modeling/SKILL.md | 15 +++++ .../.claude/skills/grill-with-docs/SKILL.md | 12 +--- .../.claude/skills/grilling/SKILL.md | 20 ++++++ .../.claude/skills/prototype/SKILL.md | 19 ++++++ .../.claude/skills/research/SKILL.md | 10 +++ .../.claude/skills/wayfinder/SKILL.md | 65 +++++++++++++++++++ .../argos/workspaces/argos-dev/CLAUDE.md | 2 +- 7 files changed, 133 insertions(+), 10 deletions(-) create mode 100644 software/application-software/argos/workspaces/argos-dev/.claude/skills/domain-modeling/SKILL.md create mode 100644 software/application-software/argos/workspaces/argos-dev/.claude/skills/grilling/SKILL.md create mode 100644 software/application-software/argos/workspaces/argos-dev/.claude/skills/prototype/SKILL.md create mode 100644 software/application-software/argos/workspaces/argos-dev/.claude/skills/research/SKILL.md create mode 100644 software/application-software/argos/workspaces/argos-dev/.claude/skills/wayfinder/SKILL.md diff --git a/software/application-software/argos/workspaces/argos-dev/.claude/skills/domain-modeling/SKILL.md b/software/application-software/argos/workspaces/argos-dev/.claude/skills/domain-modeling/SKILL.md new file mode 100644 index 0000000..e5bc259 --- /dev/null +++ b/software/application-software/argos/workspaces/argos-dev/.claude/skills/domain-modeling/SKILL.md @@ -0,0 +1,15 @@ +--- +name: domain-modeling +description: Build and sharpen Argos's domain model. Use when discussing domain terminology, editing docs/CONTEXT.md, or recording or editing an ADR. +--- + +Actively build and sharpen the domain model as you design. Merely *reading* `docs/CONTEXT.md` for vocabulary is not this skill; this is for changing the model. + +The glossary and ADRs are workspace docs, not files in `repos/argos/`: `docs/CONTEXT.md` and `docs/adr/` at the workspace root. + +- **Challenge against the glossary.** When a term conflicts with `docs/CONTEXT.md`, call it out: "The glossary defines Run as X, but you seem to mean Y. Which is it?" +- **Sharpen fuzzy language.** Propose one canonical term for vague or overloaded ones: "CAN node or tree node?" +- **Test with scenarios.** Invent edge cases that force precise boundaries between concepts. +- **Check the code.** When the user says how something works, check `repos/argos/` and surface contradictions. +- **Update `docs/CONTEXT.md` as each term resolves**, matching its existing format: one or two sentences on what a term IS, an `_Avoid_` line of rejected synonyms, overloaded terms under Flagged ambiguities. Argos-specific terms only; no implementation details. +- **Offer an ADR only** when a decision is hard to reverse, surprising without context, and a real trade-off. Name it `docs/adr/--.md` (next number, prefix per `repos/argos/docs/agents/domain.md`). A title plus 1-3 sentences of context, decision, and why is enough; add Considered Options or Consequences only when they earn it. diff --git a/software/application-software/argos/workspaces/argos-dev/.claude/skills/grill-with-docs/SKILL.md b/software/application-software/argos/workspaces/argos-dev/.claude/skills/grill-with-docs/SKILL.md index 16a6f81..345cff4 100644 --- a/software/application-software/argos/workspaces/argos-dev/.claude/skills/grill-with-docs/SKILL.md +++ b/software/application-software/argos/workspaces/argos-dev/.claude/skills/grill-with-docs/SKILL.md @@ -1,13 +1,7 @@ --- name: grill-with-docs -description: Grill the user relentlessly about a plan or design, recording the glossary and ADRs as decisions land. Use when the user wants to stress-test a plan before building, or uses any 'grill' trigger phrases. +description: A relentless interview to sharpen a plan or design, which also records the glossary and ADRs as we go. +disable-model-invocation: true --- -Interview me about every aspect of this plan until we share an understanding. Walk each branch of the design tree, resolving dependencies between decisions one by one. - -- Ask one question at a time, with your recommended answer, and wait for mine. -- Look up facts in the code yourself. Put decisions to me. If the code contradicts what I say, point it out. -- Hold me to `docs/CONTEXT.md`. Call out a term that conflicts with it, pin down fuzzy terms, and test boundaries with concrete edge-case scenarios. -- When a term is resolved, update `docs/CONTEXT.md` right away. It's a glossary only, with no implementation details. -- Offer an ADR in `docs/adr/` only when a decision is hard to reverse, surprising without context, and a real trade-off. Name it per `docs/agents/domain.md` and cover context, decision, and the alternatives considered. -- Don't enact the plan until I confirm we're aligned. Next step: `/to-spec`. +Call the Skill tool twice, for "grilling" and "domain-modeling". Next step once aligned: `/to-spec`. diff --git a/software/application-software/argos/workspaces/argos-dev/.claude/skills/grilling/SKILL.md b/software/application-software/argos/workspaces/argos-dev/.claude/skills/grilling/SKILL.md new file mode 100644 index 0000000..94021a2 --- /dev/null +++ b/software/application-software/argos/workspaces/argos-dev/.claude/skills/grilling/SKILL.md @@ -0,0 +1,20 @@ +--- +name: grilling +description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases. +--- + +Interview the user until you reach a shared understanding. Map it as a **design tree**: every decision branches into the decisions that hang off it. + +Work in **rounds**. The **frontier** is every decision whose prerequisites are settled. Ask the whole frontier at once, numbered, each with your recommended answer, then wait: + +``` +❓ **Q1** - ****: <question, with choices if any> + +➡️ <your recommended answer> +``` + +Each round of answers moves the frontier outward; recompute it and ask the next round. A question that depends on another still open this round waits for a later one. + +Facts are your job, decisions are the user's. Never ask for anything you can look up in `repos/argos/` or the workspace `docs/`: send a sub-agent, and ask the rest of the frontier while it works. + +Done when the frontier is empty and nothing is silently assumed. Don't act until the user confirms you share an understanding. diff --git a/software/application-software/argos/workspaces/argos-dev/.claude/skills/prototype/SKILL.md b/software/application-software/argos/workspaces/argos-dev/.claude/skills/prototype/SKILL.md new file mode 100644 index 0000000..21f1d7a --- /dev/null +++ b/software/application-software/argos/workspaces/argos-dev/.claude/skills/prototype/SKILL.md @@ -0,0 +1,19 @@ +--- +name: prototype +description: Build a throwaway prototype to answer one design question. Use when the user wants to check whether a state model or logic feels right, or explore what a UI should look like. +--- + +A prototype is throwaway code that answers one question. State the question in one line at the top of the prototype first. + +## Pick the shape + +- **Logic / state** ("does this model handle X then Y?"): one self-contained HTML file, no framework or server, opens by double-click. Put the logic in one `<script>` block as a pure module with no DOM access, so it lifts into real code. Pick its shape by the question: a reducer for discrete events on one state value, a state machine when which actions are legal is part of the question, pure functions when there's no ongoing state, a class when the logic owns internal state. The page shows the question, the current state as a readable panel re-rendered after every action, a button per action, and tabbed walkthroughs (happy path, an edge case, something that should be illegal). Label everything in `docs/CONTEXT.md` terms, not code names. +- **UI** ("what should this look like?"): 3 structurally different variants (max 5) on an existing angular-client route, chosen by `?variant=`, with a small floating switcher (arrows and ←/→ keys, hidden in production). Keep the route's real data; only the rendered subtree swaps. Use a new route with `prototype` in its path only if nothing can host it. Variants differ in layout and hierarchy, not colour. + +Unsure which? A backend module means logic, a page means UI; state the assumption. + +## Rules + +- Work in a ticket worktree, never `repos/argos/`. Name files so they're obviously prototypes. +- Trivial to run, in-memory state, no tests, no polish. +- When done: record the verdict on the issue, fold the validated decision into real code (rewritten properly), and commit the prototype to a throwaway `prototype/<name>` branch linked from the issue. Never merge it to `develop`. diff --git a/software/application-software/argos/workspaces/argos-dev/.claude/skills/research/SKILL.md b/software/application-software/argos/workspaces/argos-dev/.claude/skills/research/SKILL.md new file mode 100644 index 0000000..5d9545c --- /dev/null +++ b/software/application-software/argos/workspaces/argos-dev/.claude/skills/research/SKILL.md @@ -0,0 +1,10 @@ +--- +name: research +description: Investigate a question against primary sources and save cited findings as Markdown. Use when the user wants a topic researched, docs or API facts gathered, or reading delegated to a background agent. +--- + +Spin up a background agent so you keep working while it reads. Its job: + +1. Answer the question from primary sources (official docs, source code, specs, first-party APIs), tracing each claim to the source that owns it. +2. Write one Markdown file to `docs/research/<topic-slug>.md` in the workspace, citing each claim. +3. Report the path and a three-line summary. diff --git a/software/application-software/argos/workspaces/argos-dev/.claude/skills/wayfinder/SKILL.md b/software/application-software/argos/workspaces/argos-dev/.claude/skills/wayfinder/SKILL.md new file mode 100644 index 0000000..977020c --- /dev/null +++ b/software/application-software/argos/workspaces/argos-dev/.claude/skills/wayfinder/SKILL.md @@ -0,0 +1,65 @@ +--- +name: wayfinder +description: Plan a huge chunk of work (more than one agent session can hold) as a shared map of decision tickets on the Argos issue tracker, and resolve them one at a time until the way to the destination is clear. +disable-model-invocation: true +--- + +A loose idea too big for one session, wrapped in fog: the way to the **destination** (a spec to hand off, a decision to lock, or an in-place change) isn't visible yet. Chart the way as a **map** on GitHub Issues, then resolve its **decision tickets** one at a time until the route is clear. + +- **Plan, don't do.** Tickets resolve decisions, not slices of the build. The pull to just do the work means you've reached the edge of the map: hand off. The map's Notes may override this. +- **Refer by name.** Name maps and tickets by title with the link inside it, never a bare `#42`. +- **Tracker mechanics** (map, child issues, blocking, frontier query, claim, resolve): the Wayfinding operations section of `repos/argos/docs/agents/issue-tracker.md`. + +## The map + +One issue labelled `wayfinder:map`; tickets are its child issues. It's an index: a decision lives only in its ticket, the map gists and links it. Open tickets aren't listed; query for them. + +```markdown +## Destination +<what reaching the end looks like, one or two lines> + +## Notes +<domain; skills every session should consult; standing preferences> + +## Decisions so far +- [<closed ticket title>](link): <one-line gist> + +## Not yet specified +<in-scope fog you can't ticket yet> + +## Out of scope +<work ruled beyond the destination, with why and a link> +``` + +## Tickets + +A child issue sized to one 100K-token session: label `wayfinder:<type>`, body `## Question` plus the decision it resolves. Answers go in a resolution comment; assets are linked, not pasted. Claim by assigning the driving dev before any work. Blocking uses GitHub's native dependencies; the **frontier** is open, unblocked, unclaimed children. + +HITL tickets resolve only through live exchange with the human; never answer your own questions. + +- **research** (AFK): a subagent calls the Skill tool with "research". +- **prototype** (HITL): call the Skill tool with "prototype"; link the result. +- **grilling** (HITL, default): call the Skill tool for "grilling" and "domain-modeling". +- **task** (AFK, or a HITL checklist): work that must happen before a decision, like provisioning access. The answer records what was done and facts later tickets need. + +## Fog and scope + +- Ticket a question you can state precisely now, even if blocked. Otherwise write it loosely under Not yet specified; don't pre-slice it. +- Resolutions graduate fog into tickets; remove each graduated patch from Not yet specified. +- Work past the destination is out of scope, never fog. Close such a ticket and add one line under Out of scope, not Decisions so far. + +## Invocation + +At most one ticket resolved per session (research excepted). Expect other sessions editing the tracker concurrently. + +**Chart** (user gives a loose idea): +1. Grill ("grilling" + "domain-modeling") to name the destination. +2. Grill again, breadth-first, for open decisions and first steps. No fog? Stop and ask how to proceed. +3. Create the map with fog under Not yet specified, then the tickets you can specify now, then wire blocking in a second pass. +4. Start a research subagent per research ticket. Stop: charting resolves nothing. + +**Work** (user gives a map; a ticket is optional): +1. Load the map body only. Take the named ticket, else the first frontier ticket, and claim it. +2. Resolve it, zooming into related tickets and using the skills in Notes. +3. Comment the answer, close it, and add a line to Decisions so far. +4. Create-then-wire new tickets, graduate fog, rule past-destination tickets out of scope, and fix tickets the decision invalidates. diff --git a/software/application-software/argos/workspaces/argos-dev/CLAUDE.md b/software/application-software/argos/workspaces/argos-dev/CLAUDE.md index e3fabc6..afda7cf 100644 --- a/software/application-software/argos/workspaces/argos-dev/CLAUDE.md +++ b/software/application-software/argos/workspaces/argos-dev/CLAUDE.md @@ -45,7 +45,7 @@ The Argos repo is checked out at `repos/argos/`. Paths below are relative to a c ## Workflow -Idea to ship: `/grill-with-docs` → `/to-spec` → `/to-tickets` → `/implement` (test-first, then `/code-review` and `/commit`) → `/open-pr`. A trivial one-liner goes straight to `/implement`. +Idea to ship: `/grill-with-docs` → `/to-spec` → `/to-tickets` → `/implement` (test-first, then `/code-review` and `/commit`) → `/open-pr`. A trivial one-liner goes straight to `/implement`. An effort too big for one session starts with `/wayfinder`, which charts decision tickets and merges at `/to-spec`. ## PR Convention From b3aca21e8d8b190cf992094fb24a014ddc20f26f Mon Sep 17 00:00:00 2001 From: Claude <noreply@anthropic.com> Date: Sun, 27 Sep 2026 22:45:08 +0000 Subject: [PATCH 2/2] argos-dev: drop Matt Pocock's skills for now Removes grilling, grill-with-docs, domain-modeling, wayfinder, research, prototype, code-review, implement, to-spec, and to-tickets from argos-dev, and code-review from the Argos defaults. CLAUDE.md workflow is now worktree -> commit -> open-pr. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01818NEiW3BJCTrVCTDgaYDf --- .../.claude/skills/code-review/SKILL.md | 12 ---- .../.claude/skills/code-review/SKILL.md | 12 ---- .../.claude/skills/domain-modeling/SKILL.md | 15 ----- .../.claude/skills/grill-with-docs/SKILL.md | 7 -- .../.claude/skills/grilling/SKILL.md | 20 ------ .../.claude/skills/implement/SKILL.md | 14 ---- .../.claude/skills/prototype/SKILL.md | 19 ------ .../.claude/skills/research/SKILL.md | 10 --- .../argos-dev/.claude/skills/to-spec/SKILL.md | 33 ---------- .../.claude/skills/to-tickets/SKILL.md | 29 --------- .../.claude/skills/wayfinder/SKILL.md | 65 ------------------- .../argos/workspaces/argos-dev/CLAUDE.md | 4 +- 12 files changed, 2 insertions(+), 238 deletions(-) delete mode 100644 software/application-software/argos/defaults/.claude/skills/code-review/SKILL.md delete mode 100644 software/application-software/argos/workspaces/argos-dev/.claude/skills/code-review/SKILL.md delete mode 100644 software/application-software/argos/workspaces/argos-dev/.claude/skills/domain-modeling/SKILL.md delete mode 100644 software/application-software/argos/workspaces/argos-dev/.claude/skills/grill-with-docs/SKILL.md delete mode 100644 software/application-software/argos/workspaces/argos-dev/.claude/skills/grilling/SKILL.md delete mode 100644 software/application-software/argos/workspaces/argos-dev/.claude/skills/implement/SKILL.md delete mode 100644 software/application-software/argos/workspaces/argos-dev/.claude/skills/prototype/SKILL.md delete mode 100644 software/application-software/argos/workspaces/argos-dev/.claude/skills/research/SKILL.md delete mode 100644 software/application-software/argos/workspaces/argos-dev/.claude/skills/to-spec/SKILL.md delete mode 100644 software/application-software/argos/workspaces/argos-dev/.claude/skills/to-tickets/SKILL.md delete mode 100644 software/application-software/argos/workspaces/argos-dev/.claude/skills/wayfinder/SKILL.md diff --git a/software/application-software/argos/defaults/.claude/skills/code-review/SKILL.md b/software/application-software/argos/defaults/.claude/skills/code-review/SKILL.md deleted file mode 100644 index bc9952f..0000000 --- a/software/application-software/argos/defaults/.claude/skills/code-review/SKILL.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -name: code-review -description: Review the changes since a fixed point (commit, branch, tag, or merge-base) on two axes, Standards and Spec, in parallel sub-agents. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X". ---- - -1. **Fixed point.** Use the one the user gives, or ask. Confirm `git rev-parse <ref>` resolves and `git diff <ref>...HEAD` is non-empty. -2. **Spec.** Use a path the user passes, else the issue referenced in the commits, else `docs/spec/`, else ask. If there is none, skip the Spec axis. -3. **Standards.** Read `CLAUDE.md`, plus `angular-client/CLAUDE.md` and `scylla-server/CLAUDE.md` for the parts the diff touches. -4. **Two parallel `general-purpose` sub-agents**, each given the diff command and commit list, and each asked to stay under 400 words: - - **Standards** (also give it the standards files): cite each violated rule by file. Also flag Fowler code smells (duplication, feature envy, speculative generality, unclear names, …) as judgement calls. Documented rules override smells. Skip anything prettier, eslint or clippy enforces. - - **Spec** (also give it the spec): missing or partial requirements, scope creep, and wrong implementations, quoting the spec line for each. -5. **Report** under `## Standards` and `## Spec`, unmerged, and end with the finding count and worst issue per axis. diff --git a/software/application-software/argos/workspaces/argos-dev/.claude/skills/code-review/SKILL.md b/software/application-software/argos/workspaces/argos-dev/.claude/skills/code-review/SKILL.md deleted file mode 100644 index bc9952f..0000000 --- a/software/application-software/argos/workspaces/argos-dev/.claude/skills/code-review/SKILL.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -name: code-review -description: Review the changes since a fixed point (commit, branch, tag, or merge-base) on two axes, Standards and Spec, in parallel sub-agents. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X". ---- - -1. **Fixed point.** Use the one the user gives, or ask. Confirm `git rev-parse <ref>` resolves and `git diff <ref>...HEAD` is non-empty. -2. **Spec.** Use a path the user passes, else the issue referenced in the commits, else `docs/spec/`, else ask. If there is none, skip the Spec axis. -3. **Standards.** Read `CLAUDE.md`, plus `angular-client/CLAUDE.md` and `scylla-server/CLAUDE.md` for the parts the diff touches. -4. **Two parallel `general-purpose` sub-agents**, each given the diff command and commit list, and each asked to stay under 400 words: - - **Standards** (also give it the standards files): cite each violated rule by file. Also flag Fowler code smells (duplication, feature envy, speculative generality, unclear names, …) as judgement calls. Documented rules override smells. Skip anything prettier, eslint or clippy enforces. - - **Spec** (also give it the spec): missing or partial requirements, scope creep, and wrong implementations, quoting the spec line for each. -5. **Report** under `## Standards` and `## Spec`, unmerged, and end with the finding count and worst issue per axis. diff --git a/software/application-software/argos/workspaces/argos-dev/.claude/skills/domain-modeling/SKILL.md b/software/application-software/argos/workspaces/argos-dev/.claude/skills/domain-modeling/SKILL.md deleted file mode 100644 index e5bc259..0000000 --- a/software/application-software/argos/workspaces/argos-dev/.claude/skills/domain-modeling/SKILL.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -name: domain-modeling -description: Build and sharpen Argos's domain model. Use when discussing domain terminology, editing docs/CONTEXT.md, or recording or editing an ADR. ---- - -Actively build and sharpen the domain model as you design. Merely *reading* `docs/CONTEXT.md` for vocabulary is not this skill; this is for changing the model. - -The glossary and ADRs are workspace docs, not files in `repos/argos/`: `docs/CONTEXT.md` and `docs/adr/` at the workspace root. - -- **Challenge against the glossary.** When a term conflicts with `docs/CONTEXT.md`, call it out: "The glossary defines Run as X, but you seem to mean Y. Which is it?" -- **Sharpen fuzzy language.** Propose one canonical term for vague or overloaded ones: "CAN node or tree node?" -- **Test with scenarios.** Invent edge cases that force precise boundaries between concepts. -- **Check the code.** When the user says how something works, check `repos/argos/` and surface contradictions. -- **Update `docs/CONTEXT.md` as each term resolves**, matching its existing format: one or two sentences on what a term IS, an `_Avoid_` line of rejected synonyms, overloaded terms under Flagged ambiguities. Argos-specific terms only; no implementation details. -- **Offer an ADR only** when a decision is hard to reverse, surprising without context, and a real trade-off. Name it `docs/adr/<NNNN>-<prefix>-<topic-slug>.md` (next number, prefix per `repos/argos/docs/agents/domain.md`). A title plus 1-3 sentences of context, decision, and why is enough; add Considered Options or Consequences only when they earn it. diff --git a/software/application-software/argos/workspaces/argos-dev/.claude/skills/grill-with-docs/SKILL.md b/software/application-software/argos/workspaces/argos-dev/.claude/skills/grill-with-docs/SKILL.md deleted file mode 100644 index 345cff4..0000000 --- a/software/application-software/argos/workspaces/argos-dev/.claude/skills/grill-with-docs/SKILL.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -name: grill-with-docs -description: A relentless interview to sharpen a plan or design, which also records the glossary and ADRs as we go. -disable-model-invocation: true ---- - -Call the Skill tool twice, for "grilling" and "domain-modeling". Next step once aligned: `/to-spec`. diff --git a/software/application-software/argos/workspaces/argos-dev/.claude/skills/grilling/SKILL.md b/software/application-software/argos/workspaces/argos-dev/.claude/skills/grilling/SKILL.md deleted file mode 100644 index 94021a2..0000000 --- a/software/application-software/argos/workspaces/argos-dev/.claude/skills/grilling/SKILL.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -name: grilling -description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases. ---- - -Interview the user until you reach a shared understanding. Map it as a **design tree**: every decision branches into the decisions that hang off it. - -Work in **rounds**. The **frontier** is every decision whose prerequisites are settled. Ask the whole frontier at once, numbered, each with your recommended answer, then wait: - -``` -❓ **Q1** - **<title>**: <question, with choices if any> - -➡️ <your recommended answer> -``` - -Each round of answers moves the frontier outward; recompute it and ask the next round. A question that depends on another still open this round waits for a later one. - -Facts are your job, decisions are the user's. Never ask for anything you can look up in `repos/argos/` or the workspace `docs/`: send a sub-agent, and ask the rest of the frontier while it works. - -Done when the frontier is empty and nothing is silently assumed. Don't act until the user confirms you share an understanding. diff --git a/software/application-software/argos/workspaces/argos-dev/.claude/skills/implement/SKILL.md b/software/application-software/argos/workspaces/argos-dev/.claude/skills/implement/SKILL.md deleted file mode 100644 index d456f78..0000000 --- a/software/application-software/argos/workspaces/argos-dev/.claude/skills/implement/SKILL.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -name: implement -description: Implement a piece of work based on a spec or set of tickets. -disable-model-invocation: true ---- - -Implement the ticket(s) the user names, one ticket per fresh context, each in its own worktree at `repos/worktrees/argos/<branch>/` (never in `repos/argos/`). Create the worktree first if it doesn't exist. - -1. Work test-first at the spec's agreed seams, one behavior at a time: write a failing test, then the minimum code to pass it, and refactor only while green. Test behavior through public interfaces, and mock only at system boundaries. -2. Check as you go: - - **Frontend:** single specs with `ng test --include='src/**/thing.spec.ts' --watch=false` while iterating. At the end, run `ng test --watch=false` (bare `ng test` watches and blocks the shell), then the lint and format checks. - - **Backend:** `cargo build` and single tests while iterating, `cargo test` at the end. -3. Review with `/code-review` against `develop`, and fix what it finds. -4. Commit with `/commit`. Don't push or open a PR unless asked; that's `/open-pr`. diff --git a/software/application-software/argos/workspaces/argos-dev/.claude/skills/prototype/SKILL.md b/software/application-software/argos/workspaces/argos-dev/.claude/skills/prototype/SKILL.md deleted file mode 100644 index 21f1d7a..0000000 --- a/software/application-software/argos/workspaces/argos-dev/.claude/skills/prototype/SKILL.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -name: prototype -description: Build a throwaway prototype to answer one design question. Use when the user wants to check whether a state model or logic feels right, or explore what a UI should look like. ---- - -A prototype is throwaway code that answers one question. State the question in one line at the top of the prototype first. - -## Pick the shape - -- **Logic / state** ("does this model handle X then Y?"): one self-contained HTML file, no framework or server, opens by double-click. Put the logic in one `<script>` block as a pure module with no DOM access, so it lifts into real code. Pick its shape by the question: a reducer for discrete events on one state value, a state machine when which actions are legal is part of the question, pure functions when there's no ongoing state, a class when the logic owns internal state. The page shows the question, the current state as a readable panel re-rendered after every action, a button per action, and tabbed walkthroughs (happy path, an edge case, something that should be illegal). Label everything in `docs/CONTEXT.md` terms, not code names. -- **UI** ("what should this look like?"): 3 structurally different variants (max 5) on an existing angular-client route, chosen by `?variant=`, with a small floating switcher (arrows and ←/→ keys, hidden in production). Keep the route's real data; only the rendered subtree swaps. Use a new route with `prototype` in its path only if nothing can host it. Variants differ in layout and hierarchy, not colour. - -Unsure which? A backend module means logic, a page means UI; state the assumption. - -## Rules - -- Work in a ticket worktree, never `repos/argos/`. Name files so they're obviously prototypes. -- Trivial to run, in-memory state, no tests, no polish. -- When done: record the verdict on the issue, fold the validated decision into real code (rewritten properly), and commit the prototype to a throwaway `prototype/<name>` branch linked from the issue. Never merge it to `develop`. diff --git a/software/application-software/argos/workspaces/argos-dev/.claude/skills/research/SKILL.md b/software/application-software/argos/workspaces/argos-dev/.claude/skills/research/SKILL.md deleted file mode 100644 index 5d9545c..0000000 --- a/software/application-software/argos/workspaces/argos-dev/.claude/skills/research/SKILL.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -name: research -description: Investigate a question against primary sources and save cited findings as Markdown. Use when the user wants a topic researched, docs or API facts gathered, or reading delegated to a background agent. ---- - -Spin up a background agent so you keep working while it reads. Its job: - -1. Answer the question from primary sources (official docs, source code, specs, first-party APIs), tracing each claim to the source that owns it. -2. Write one Markdown file to `docs/research/<topic-slug>.md` in the workspace, citing each claim. -3. Report the path and a three-line summary. diff --git a/software/application-software/argos/workspaces/argos-dev/.claude/skills/to-spec/SKILL.md b/software/application-software/argos/workspaces/argos-dev/.claude/skills/to-spec/SKILL.md deleted file mode 100644 index 2c37192..0000000 --- a/software/application-software/argos/workspaces/argos-dev/.claude/skills/to-spec/SKILL.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -name: to-spec -description: Turn the current conversation into a spec, review it as a PR, then publish it as an issue. No interview, just synthesis. -disable-model-invocation: true ---- - -Synthesize a spec from the conversation and the codebase. Don't interview the user. - -1. **Tracking issue.** Use the existing issue, or create a stub one. Its number names the branch (`{issue-number}-{slug}`). -2. **Explore** the code in the area, using `docs/CONTEXT.md` terms and respecting its ADRs. -3. **Test seams.** Propose where the feature will be tested: prefer existing seams, as high as possible, ideally one. Confirm with the user. -4. **Write** `docs/spec/<name>/spec.md` from the template and open it as a PR. Follow `docs/agents/spec-review.md` for review, publishing to the issue with `ready-for-agent`, and removing the file afterwards. - -<spec-template> -## Problem Statement -The problem, from the user's perspective. - -## Solution -The solution, from the user's perspective. - -## User Stories -An extensive numbered list: "As a <actor>, I want <feature>, so that <benefit>". - -## Implementation Decisions -Modules built or changed and their interfaces, architecture, schema and API contracts, and key interactions. - -## Testing Decisions -The agreed seams, which modules get tested, and prior art. Test external behavior only. - -## Out of Scope - -## Further Notes -</spec-template> diff --git a/software/application-software/argos/workspaces/argos-dev/.claude/skills/to-tickets/SKILL.md b/software/application-software/argos/workspaces/argos-dev/.claude/skills/to-tickets/SKILL.md deleted file mode 100644 index 13e83a4..0000000 --- a/software/application-software/argos/workspaces/argos-dev/.claude/skills/to-tickets/SKILL.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -name: to-tickets -description: Break a plan, spec, or the current conversation into tracer-bullet tickets with blocking edges, published to the issue tracker. Use when the user wants to turn a plan into issues or break down work. -disable-model-invocation: true ---- - -1. **Context.** Work from the conversation. If given a spec or issue, read its body and comments. Explore the code if needed, looking for prefactors that make the change easy. -2. **Slice** into tracer bullets. Each ticket: - - is a narrow but complete path through every layer (schema, API, UI, tests), demoable on its own, and fits one fresh context; - - is AFK (no human needed) where possible, HITL otherwise; - - lists the tickets that block it. Prefactors go first. - - A wide mechanical refactor (rename a column, retype a shared symbol) can't land as a vertical slice. Sequence it expand → migrate in batches → contract, one ticket per step. -3. **Quiz.** Show a numbered list of title, AFK/HITL, blocked by, and what it delivers. Ask about granularity, blocking edges, merges or splits, and AFK/HITL. Iterate until approved. -4. **Create** the issues in dependency order with `ready-for-agent`. Link blockers, and set `Parent` to the spec issue only if one exists. Don't modify the parent. - -<issue-template> -## Parent -The spec issue (omit if none). - -## What to build -The end-to-end behavior, from the user's perspective. - -## Acceptance criteria -- [ ] … - -## Blocked by -Blocking tickets, or "None — can start immediately". -</issue-template> diff --git a/software/application-software/argos/workspaces/argos-dev/.claude/skills/wayfinder/SKILL.md b/software/application-software/argos/workspaces/argos-dev/.claude/skills/wayfinder/SKILL.md deleted file mode 100644 index 977020c..0000000 --- a/software/application-software/argos/workspaces/argos-dev/.claude/skills/wayfinder/SKILL.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -name: wayfinder -description: Plan a huge chunk of work (more than one agent session can hold) as a shared map of decision tickets on the Argos issue tracker, and resolve them one at a time until the way to the destination is clear. -disable-model-invocation: true ---- - -A loose idea too big for one session, wrapped in fog: the way to the **destination** (a spec to hand off, a decision to lock, or an in-place change) isn't visible yet. Chart the way as a **map** on GitHub Issues, then resolve its **decision tickets** one at a time until the route is clear. - -- **Plan, don't do.** Tickets resolve decisions, not slices of the build. The pull to just do the work means you've reached the edge of the map: hand off. The map's Notes may override this. -- **Refer by name.** Name maps and tickets by title with the link inside it, never a bare `#42`. -- **Tracker mechanics** (map, child issues, blocking, frontier query, claim, resolve): the Wayfinding operations section of `repos/argos/docs/agents/issue-tracker.md`. - -## The map - -One issue labelled `wayfinder:map`; tickets are its child issues. It's an index: a decision lives only in its ticket, the map gists and links it. Open tickets aren't listed; query for them. - -```markdown -## Destination -<what reaching the end looks like, one or two lines> - -## Notes -<domain; skills every session should consult; standing preferences> - -## Decisions so far -- [<closed ticket title>](link): <one-line gist> - -## Not yet specified -<in-scope fog you can't ticket yet> - -## Out of scope -<work ruled beyond the destination, with why and a link> -``` - -## Tickets - -A child issue sized to one 100K-token session: label `wayfinder:<type>`, body `## Question` plus the decision it resolves. Answers go in a resolution comment; assets are linked, not pasted. Claim by assigning the driving dev before any work. Blocking uses GitHub's native dependencies; the **frontier** is open, unblocked, unclaimed children. - -HITL tickets resolve only through live exchange with the human; never answer your own questions. - -- **research** (AFK): a subagent calls the Skill tool with "research". -- **prototype** (HITL): call the Skill tool with "prototype"; link the result. -- **grilling** (HITL, default): call the Skill tool for "grilling" and "domain-modeling". -- **task** (AFK, or a HITL checklist): work that must happen before a decision, like provisioning access. The answer records what was done and facts later tickets need. - -## Fog and scope - -- Ticket a question you can state precisely now, even if blocked. Otherwise write it loosely under Not yet specified; don't pre-slice it. -- Resolutions graduate fog into tickets; remove each graduated patch from Not yet specified. -- Work past the destination is out of scope, never fog. Close such a ticket and add one line under Out of scope, not Decisions so far. - -## Invocation - -At most one ticket resolved per session (research excepted). Expect other sessions editing the tracker concurrently. - -**Chart** (user gives a loose idea): -1. Grill ("grilling" + "domain-modeling") to name the destination. -2. Grill again, breadth-first, for open decisions and first steps. No fog? Stop and ask how to proceed. -3. Create the map with fog under Not yet specified, then the tickets you can specify now, then wire blocking in a second pass. -4. Start a research subagent per research ticket. Stop: charting resolves nothing. - -**Work** (user gives a map; a ticket is optional): -1. Load the map body only. Take the named ticket, else the first frontier ticket, and claim it. -2. Resolve it, zooming into related tickets and using the skills in Notes. -3. Comment the answer, close it, and add a line to Decisions so far. -4. Create-then-wire new tickets, graduate fog, rule past-destination tickets out of scope, and fix tickets the decision invalidates. diff --git a/software/application-software/argos/workspaces/argos-dev/CLAUDE.md b/software/application-software/argos/workspaces/argos-dev/CLAUDE.md index afda7cf..c9dcf84 100644 --- a/software/application-software/argos/workspaces/argos-dev/CLAUDE.md +++ b/software/application-software/argos/workspaces/argos-dev/CLAUDE.md @@ -45,7 +45,7 @@ The Argos repo is checked out at `repos/argos/`. Paths below are relative to a c ## Workflow -Idea to ship: `/grill-with-docs` → `/to-spec` → `/to-tickets` → `/implement` (test-first, then `/code-review` and `/commit`) → `/open-pr`. A trivial one-liner goes straight to `/implement`. An effort too big for one session starts with `/wayfinder`, which charts decision tickets and merges at `/to-spec`. +Per ticket: `new-worktree` → implement and test in the worktree → `/commit` → `/open-pr`. ## PR Convention @@ -65,7 +65,7 @@ Frontend and backend conventions live alongside their code and auto-load when ed ## Issue tracker -Issues live in GitHub Issues on `Northeastern-Electric-Racing/Argos` via the `gh` CLI. See `docs/agents/issue-tracker.md` for title, label, and assignment conventions, and `docs/agents/triage-labels.md` for labels. Specs and tickets avoid file paths and code snippets; they go stale. +Issues live in GitHub Issues on `Northeastern-Electric-Racing/Argos` via the `gh` CLI. See `docs/agents/issue-tracker.md` for title, label, and assignment conventions. ## Domain docs