@bastani/atomic 0.7.17 → 0.8.0

package/dist/builtin/subagents/prompts/parallel-handoff-plan.md

@@ -0,0 +1,77 @@
+---
+description: Parallel external + local research builders into an implementation handoff plan
+---
+
+Use parallel subagents to understand the request, compare any external references, inspect the local codebase, and produce a grounded implementation handoff plan with a final implementation-ready meta-prompt.
+
+Primary request, target, or focus:
+
+$@
+
+Use `context: "fresh"` unless I explicitly ask for forked context. First read or fetch any URLs, issue links, PRs, screenshots, plans, docs, or local files mentioned in the request. Treat them as primary scope, not optional context.
+
+Use the `subagent` tool in chain mode. The chain has one parallel discovery step followed by a parent-side synthesis pass (there is no dedicated synthesizer subagent in this skill):
+
+Parallel discovery step. Choose the specialists that apply:
+
+- `codebase-online-researcher` — required whenever the request mentions external projects, libraries, docs, APIs, recent changes, or best-practice guidance. It web-searches, fetches authoritative sources, and persists keepers under `research/web/`.
+- `codebase-locator` — required for any non-trivial code change. Find the local files, tests, fixtures, and configs the change would touch.
+- `codebase-analyzer` — required when the local behavior matters. Trace the relevant flow with `file:line` references.
+- `codebase-pattern-finder` — add when transferable conventions or analogous implementations would shape the plan.
+- `codebase-research-locator` and `codebase-research-analyzer` — add when prior `research/` or `specs/` docs likely apply. Run them sequentially (locator first, then analyzer) or pair them inside the parallel step with distinct output paths.
+
+Use distinct output paths under the chain directory. Example outputs:
+
+- `handoff/external-reference.md`
+- `handoff/local-files.md`
+- `handoff/local-flow.md`
+- `handoff/local-patterns.md`
+- `handoff/prior-research.md`
+
+Do not write these artifacts into the repository unless I explicitly ask for persistent files.
+
+Role guidance:
+
+External researcher (`codebase-online-researcher`):
+
+- Study linked projects, docs, issues, examples, source code, or prompt guidance.
+- Identify the behavior, API, implementation files, constraints, and transferable ideas.
+- Use `fetch_content` first, then `/llms.txt`, then `Accept: text/markdown`, and only fall back to `playwright-cli` when JS execution or auth is required.
+- Persist any high-value fetch to `research/web/<YYYY-MM-DD>-<topic>.md`.
+- Return source links, repo paths, key evidence, risks, and what matters for this implementation.
+
+Local locator + analyzer (`codebase-locator`, `codebase-analyzer`):
+
+- Locator returns the full file map grouped by purpose.
+- Analyzer reads the located files and traces the current implementation, control flow, transformations, and constraints with `file:line` citations.
+- Together they cover "where it lives" and "how it works today" without overlap.
+
+Local pattern-finder (`codebase-pattern-finder`), when used:
+
+- Find similar implementations or conventions worth modeling after. Include working snippets with `file:line` references.
+
+Prior research (`codebase-research-locator` → `codebase-research-analyzer`), when used:
+
+- Locator surfaces the relevant dated docs from `research/` and `specs/`.
+- Analyzer extracts the decisions, constraints, and lessons that are still applicable, flagging anything superseded by newer docs.
+
+Parent-side synthesis after the discovery step returns:
+
+- Compare external evidence against the local architecture.
+- Propose the safest implementation shape, the likely files to change, edge cases, validation commands, and decisions that need approval.
+- Write `handoff/final-handoff-plan.md` yourself, or summarize inline if I didn't ask for a persisted artifact.
+
+Include in the final handoff:
+
+- what the feature or change should do;
+- what the external reference teaches;
+- what the local codebase implies;
+- the recommended approach;
+- likely files to change;
+- constraints, non-goals, validation, risks;
+- unresolved questions;
+- a compact implementation-ready meta-prompt for the next writer.
+
+After the chain returns, summarize the result for me with the recommended approach, artifact paths, the final meta-prompt, and any questions or assumptions that remain.
+
+Do not start implementation from this command unless I explicitly ask for it.

package/dist/builtin/subagents/prompts/parallel-research.md

@@ -0,0 +1,58 @@
+---
+description: Parallel research specialists for grounded answers
+---
+
+Launch parallel research specialists to build a grounded answer to the current question or decision.
+
+Use fresh context, not forked context, unless I explicitly ask for forked context. Specialists should inspect sources directly instead of relying on the main conversation history.
+
+Choose specialists based on the question:
+
+- `codebase-online-researcher` — web, docs, standards, ecosystem, recent changes, benchmarks, and primary-source evidence.
+- `codebase-locator` — repository files that touch the question.
+- `codebase-analyzer` — how the relevant code currently works, with `file:line` references.
+- `codebase-pattern-finder` — comparable implementations or conventions already in the codebase.
+- `codebase-research-locator` and `codebase-research-analyzer` — prior `research/` or `specs/` docs that bear on the question (run locator first, then analyzer).
+
+Give each specialist a distinct angle. Unless I specify angles, use three of these (skip the ones that don't apply):
+
+1. External evidence — `codebase-online-researcher`
+   Find current, authoritative sources: official docs, specs, release notes, benchmarks, issue threads, or primary explanations.
+
+2. Local code context — `codebase-locator` and/or `codebase-analyzer`
+   Locate the relevant files and trace how they work today.
+
+3. Local conventions — `codebase-pattern-finder`
+   Surface analogous implementations or patterns the answer should respect.
+
+4. Prior decisions — `codebase-research-locator` followed by `codebase-research-analyzer`
+   When the topic has history in `research/` or `specs/`, extract the decisions and constraints that still apply.
+
+Adapt the angles when the question calls for it:
+
+- Library/API questions: include `codebase-online-researcher` for official docs and recent examples.
+- Architecture decisions: include `codebase-locator` and `codebase-pattern-finder` for module boundaries and dependency direction.
+- Debugging questions: include `codebase-analyzer` for call paths and `codebase-online-researcher` for the error message.
+- UI/product questions: include `codebase-pattern-finder` for analogous components and `codebase-online-researcher` for design precedent.
+- Time-sensitive topics: have the online researcher prefer 2026/2025 sources and persist findings to `research/web/`.
+
+Prefer two or three strong specialists over many vague ones. None of these agents should edit files — this is a research pass only unless I explicitly ask for implementation.
+
+Ask each specialist to return concise findings with evidence:
+
+- file paths and line ranges for local findings;
+- source links for external findings;
+- confidence level and gaps;
+- recommended next step or decision implication.
+
+After the specialists return, synthesize the answer into:
+
+- what we know;
+- what the local codebase implies;
+- tradeoffs and risks;
+- gaps or assumptions;
+- the recommended next move.
+
+If findings disagree, call out the disagreement instead of smoothing it over.
+
+$@

package/dist/builtin/subagents/prompts/parallel-review.md

@@ -0,0 +1,52 @@
+---
+description: Parallel specialist review of the current work
+---
+
+Launch parallel specialists for an adversarial review of the current work.
+
+Use fresh context, not forked context, unless I explicitly ask for forked context. Specialists should inspect the repository, relevant instructions, and current diff directly from files and commands. Do not rely on the main conversation history.
+
+There is no generic `reviewer` agent — assemble the review from read-only specialists with distinct angles. Generate the angles dynamically from the user's intent, the plan, the implemented code, and the current diff. If I specify angles, use mine. Otherwise pick three of the following:
+
+1. Correctness and regressions — `codebase-analyzer`
+   Trace the current diff and the surrounding flow to check whether the change satisfies the request, preserves existing behavior, handles edge cases, and avoids hidden runtime failures. Cite `file:line` for every claim.
+
+2. Bug and failure-mode hunt — `debugger`
+   Treat the diff as a suspect change. Reproduce the relevant behavior when possible, hypothesize how it could break, and report findings with evidence. The `debugger` agent can write fixes — for this pass, explicitly instruct it to inspect and report only, not edit.
+
+3. Pattern fit and consistency — `codebase-pattern-finder`
+   Compare the implementation against existing analogous patterns and conventions in the codebase. Flag drift, divergence from established structure, or missed reuse opportunities with `file:line` snippets.
+
+4. Prior decisions and constraints — `codebase-research-locator` then `codebase-research-analyzer`
+   When prior research or specs likely constrain the change, surface the relevant docs and extract the decisions the new code must honor.
+
+5. External-spec or API conformance — `codebase-online-researcher`
+   When the change implements an external contract (API, RFC, library behavior), verify the implementation against the authoritative source.
+
+Cleanup-style angles (simplicity, slop, verbosity) belong in `/parallel-cleanup`; use that instead of overloading this pass.
+
+Give every specialist a specific task prompt naming its angle. Ask them to return concise, evidence-backed findings with file/line references and suggested fixes. The response should be review feedback, not a context summary. Specialists must not edit files in this pass, even when the agent type can — say so explicitly in the prompt.
+
+While they run, do your own narrow inspection if useful. After they return, synthesize the feedback into:
+
+- fixes worth doing now;
+- optional improvements;
+- feedback to ignore or defer, with a short reason.
+
+Do not blindly apply every finding.
+
+Autofix mode: if the invocation contains the exact word `autofix`, treat it as workflow control, not review scope. Remove it before deciding the review target. After synthesis, launch a single async writer (`debugger` for correctness or regression fixes, `code-simplifier` for cleanup-shaped feedback) with the explicit fix list as scope. Validate, and summarize. Do not apply optional improvements unless explicitly requested. If there are no fixes worth doing now, do not edit.
+
+Without autofix mode, ask before applying fixes unless I already told you to address review feedback. When you ask, end with a compact numbered menu so I can respond with a number. Use wording suited to the findings, but include these choices when applicable:
+
+```text
+Reply with [1], [2], or further instructions:
+[1] Apply only the fixes worth doing now.
+[2] Apply the fixes worth doing now plus optional improvements.
+```
+
+Additional review target or focus from the slash command invocation:
+
+$@
+
+If the invocation provides a URL, issue link, file path, plan path, or freeform focus, treat it as the primary review scope. Read or fetch that target before assigning reviewer angles, and pass the target explicitly into each specialist task.

package/dist/builtin/subagents/prompts/review-loop.md

@@ -0,0 +1,48 @@
+---
+description: Specialist review/fix loop until clean
+---
+
+Run a parent-orchestrated review-and-fix loop for the requested work.
+
+Use the `subagent` tool. Keep the parent session as the loop controller and final decision-maker. Child subagents must receive concrete role-specific tasks; they must not run subagents or manage the loop themselves.
+
+There is no generic worker or reviewer in this skill — the loop composes specialist agents:
+
+- Writers (one per pass): `debugger` for bug fixes, correctness/regression fixes, or behavior changes; `code-simplifier` for cleanup, refinement, or simplification.
+- Read-only reviewers (parallel each round): `codebase-analyzer` for correctness and flow; `debugger` in inspect-only mode for failure-mode hunts; `codebase-pattern-finder` for consistency; `codebase-online-researcher` for external-spec conformance; `codebase-research-locator` + `codebase-research-analyzer` for prior decisions.
+
+Default to a maximum of 3 review rounds unless I specify a different cap. Count a review round each time fresh-context reviewers inspect the current diff after a writer pass. Stop early when reviewers find no blockers or fixes worth doing now.
+
+If the invocation includes an implementation request, first launch one async writer for the approved scope — `debugger` when the work is correctness-shaped, `code-simplifier` when it is refinement-shaped. If the current diff is already the target, start with review. The sequence can be launched up front as an async/background chain when the workflow is clear, or continued as follow-up subagent runs after each async completion. For an initial chain, pass `async: true` so the main chat is unblocked; do not set `clarify: true` unless I explicitly want the foreground clarify UI. Use only one writer against the active worktree at a time unless I explicitly ask for isolated worktrees.
+
+For each review round, launch fresh-context read-only reviewer specialists in parallel. They must inspect the repository, relevant instructions, and current diff directly from files and commands. They must not rely on the main conversation history and must not edit files — when using `debugger` for this pass, explicitly tell it to inspect and report only.
+
+Choose review angles from the actual change. Common angles are correctness/regressions (`codebase-analyzer`), failure-mode hunt (`debugger` inspect-only), and pattern fit (`codebase-pattern-finder`). Add external-spec (`codebase-online-researcher`) or prior-decision (`codebase-research-*`) angles when the work calls for it. Prefer three strong reviewers over many vague reviewers.
+
+After reviewers return, synthesize their feedback into:
+
+- blockers or scope/product/architecture decisions that need user approval;
+- fixes worth doing now;
+- optional improvements;
+- feedback to ignore or defer, with a short reason.
+
+Do not blindly apply every finding. If reviewers surface an unapproved product, scope, or architecture decision, pause and ask me before launching a fix writer.
+
+When an async implementation writer completes, treat its handoff as the transition into review, not as final completion, unless I explicitly asked for writer-only work, review-only output, or to stop after implementation.
+
+When there are fixes worth doing now and the workflow is implementation-authorized, launch one async writer to apply only those synthesized fixes — `debugger` for correctness fixes, `code-simplifier` for cleanup fixes. Ask it to preserve the approved scope, run focused validation, and report changed files, commands run with exit codes, validation evidence, surprises, and anything left undone.
+
+After a fix writer returns, run another review round only when it made material changes or addressed non-trivial findings. Do not keep looping for optional polish, speculative improvements, or findings already deferred by the parent.
+
+Stop and summarize when one of these is true:
+
+- reviewers find no blockers or fixes worth doing now;
+- remaining feedback is optional, speculative, or intentionally deferred;
+- reviewers surface an unapproved decision that needs me;
+- the max review-round cap is reached.
+
+On completion, inspect the final diff yourself, run or confirm focused validation where appropriate, and summarize the loop: rounds run, fixes applied, validation, remaining deferred items, and why the loop stopped.
+
+Additional target, implementation request, max-iteration cap, or review focus from the slash command invocation:
+
+$@