From arn-code
This skill should be used when the user says "planning", "arness planning", "plan a feature", "start planning", "I want to build", "new feature", "plan something", "what should I build", "pick an issue", "plan a bug fix", "I have an idea", "spec and plan", "plan from scratch", "plan this", "feature planning", "bug planning", "plan this issue", "arn-planning", or wants to go from an idea, issue, or bug report through to a complete implementation plan ready for execution. Handles severity-aware scope routing across three ceremony tiers (swift, standard, thorough), routing between feature specs, bug specs, and quick implementations, and produces a reviewed plan ready for execution. Chains to arn-implementing at completion.
npx claudepluginhub appsvortex/arness --plugin arn-codeThis skill uses the workspace's default tool permissions.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.
Go from an idea, issue, or bug report through to a complete implementation plan ready for execution. This is the primary first-citizen entry point for the Arness development pipeline. It orchestrates scope assessment, spec authoring, plan generation, plan structuring, plan review, and task creation — then chains to arn-implementing.
This skill is a sequencer and decision-gate handler. It MUST NOT duplicate sub-skill logic. All pipeline work is done by the invoked skills. Arness-planning handles: input routing, scope assessment, transitions between skills, progress display, resumability, and chaining.
Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-ensure-config/references/ensure-config.md and follow its instructions. This guarantees a user profile exists and ## Arness is configured with Arness Code fields before proceeding.
After configuration is ensured, extract the following from ## Arness:
github, jira, or none)Check the trigger message to determine the entry path:
| Input Pattern | Action |
|---|---|
| No args | Proceed to Step 1 (State Detection), then G1 if no resume |
| Text description (e.g., "planning: add rate limiting") | Extract description, proceed to Step 3 (Scope Assessment) |
Issue reference (#42, PROJ-123) | Invoke Skill: arn-code:arn-code-pick-issue with the reference, then proceed to Step 3 with the loaded issue context |
Feature backlog reference (F-003) | Invoke Skill: arn-code:arn-code-pick-issue with the reference, then proceed to Step 3 |
| "pick" keyword | Invoke Skill: arn-code:arn-code-pick-issue (browse mode), then proceed to Step 3 |
| "resume" | Proceed to Step 1 (State Detection) |
Check which artifacts exist on disk to determine the entry point. Check from most advanced to least advanced — first match wins:
| Artifact | Detected State | Resume Point |
|---|---|---|
INTRODUCTION.md in <plans-dir>/<project>/ | Plan saved and structured | G5 (Completion — offer implementing) |
STANDARD_*.md in <plans-dir>/ or project root | Standard tier in progress/complete | Chain to arn-implementing with standard intent |
PLAN_PREVIEW_*.md in <plans-dir>/ | Plan generated, not saved | Auto-run save-plan, then G5 |
FEATURE_*.md or BUGFIX_*.md in <specs-dir>/ (finalized) | Spec written, no plan | G3 (Spec review) |
DRAFT_FEATURE_*.md in <specs-dir>/ (no finalized spec) | Spec in progress | Resume spec (invoke feature-spec, which detects the draft) |
| None of the above | Fresh start | G1 |
If multiple specs or plans detected: List them and ask the user which to resume.
If artifacts detected:
Show the detected state and ask: "It looks like you have an in-progress plan. Resume from [detected stage], or start fresh?"
If no artifacts detected: check for a greenfield feature backlog, then proceed to G1.
Greenfield backlog check (optional — Arness Spark integration):
If no Arness Code artifacts were detected, check for a greenfield feature backlog. Arness Spark is an optional plugin — if any condition fails, skip silently and proceed to G1 normally.
## Arness config has a Vision directory field (only set by arn-spark-init, never by core arn-code-init)<vision-dir>/features/feature-backlog.md exists## Feature Tracker tableIf all three pass, parse the Feature Tracker to count features by status (pending, in-progress, done). Skip rows with status decomposed — their sub-features are counted individually instead. Calculate unblocked features (pending where all dependencies have status done, or dependencies are None).
Hold the results for G1 — they change how the gate is presented. If any condition fails, proceed to G1 with no backlog context.
Only reached when no input was provided and no artifacts were detected for resume.
Show progress:
Planning: ENTRY -> scope-router -> spec -> plan -> save -> review-plan -> taskify -> [ready]
^^^^^
If greenfield backlog was detected in Step 1:
Present the backlog context before asking:
"A greenfield feature backlog exists with [total] features ([unblocked] unblocked, [in-progress] in progress, [done] done).
The unblocked features ready for implementation are available via the backlog."
Ask (using AskUserQuestion):
"What would you like to work on?"
If unblocked > 1 (batch option available — 4 options):
Options:
If unblocked <= 1 (no batch option — 3 options):
Options:
none OR greenfield backlog was detected — the greenfield backlog provides local-only browsing even without a remote issue tracker)If no greenfield backlog (default):
Ask (using AskUserQuestion):
"What are you planning?"
Options:
none)Based on choice:
Skill: arn-code:arn-code-pick-issue. When pick-issue completes (issue selected and context loaded), proceed to Step 3 (Scope Assessment) with the issue context.Skill: arn-code:arn-code-batch-planning. Exit arn-planning — batch-planning orchestrates the multi-feature flow including spec, plan, save-plan for each feature, then chains to batch-implement.Skill: arn-code:arn-code-bug-spec. Bug-spec handles its own investigation flow:
/arn-shipping or exit.Classify the user's input to determine the best routing. This is a lightweight assessment, not a full architect invocation.
Show progress:
Planning: entry -> SCOPE-ROUTER -> spec -> plan -> save -> review-plan -> taskify -> [ready]
^^^^^^^^^^^^
Read (silently, do not present to the user):
<code-patterns-dir>/architecture.md — technology stack, project scale, module structure<code-patterns-dir>/code-patterns.md — naming conventions, existing patternsAnalyze the description (from user input, issue, or backlog item) for intent signals:
Bug signals: "fix", "broken", "error", "not working", "bug", "crash", "failing", "regression", "issue with", "doesn't work", "wrong behavior" → TYPE = bug
Feature signals: "add", "create", "build", "implement", "new", "support for", "enable", "introduce", "enhance", "improve", "extend", "upgrade" → TYPE = feature
Ambiguous (no clear signals or mixed signals):
→ Ask (using AskUserQuestion): "Is this a bug fix or a new feature?"
For TYPE = bug, skip scope routing — always route to bug-spec.
For TYPE = feature, apply the severity-aware scope router:
Read criteria: Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-planning/references/scope-router-criteria.md
Supplementary signal (optional): If there is a working tree with changes, run git diff --stat silently as a supplementary signal for file count and cross-module impact. This does not override the description-based assessment but can confirm or adjust estimates.
Score each criterion: Rate each of the 6 criteria (low=0, medium=1, high=2), multiply by its weight, and compute the weighted total (0-20).
Apply override rules: Check if any override rules from the criteria reference force a minimum tier (e.g., any high-weight criterion scoring "high" forces minimum standard).
Map to recommended tier:
Based on TYPE and recommended tier:
TYPE = bug → Skill: arn-code:arn-code-bug-spec
TYPE = feature → Gate G2 (Tier Selection) with the recommended tier
Only reached for TYPE = feature. Present the scope router recommendation and let the user confirm or override.
Show progress:
Planning [<recommended-tier>]: entry -> SCOPE-ROUTER -> spec -> plan -> save -> review-plan -> taskify -> [ready]
^^^^^^^^^^^^
Present the recommendation as a one-sentence summary: "Based on [key factors], I recommend [tier] for this change."
Ask (using AskUserQuestion):
"Recommended tier: [tier]. How would you like to proceed?"
Options (dynamically ordered — recommended tier is always option 1):
If recommended tier is swift:
If recommended tier is standard:
If recommended tier is thorough:
Based on the user's selection:
Swift: Skill: arn-code:arn-implementing (with swift intent + the description as context). Exit planning — implementing takes over.
Standard: Skill: arn-code:arn-implementing (with standard intent + the description as context). Exit planning — implementing takes over.
Thorough: Proceed to feature spec. If the user upgraded to thorough from a lower recommendation, skip the expert debate question and proceed directly to Skill: arn-code:arn-code-feature-spec. Otherwise, check the expert-debate preference:
Preference check: Read pipeline.expert-debate using the two-tier lookup chain (see ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-ensure-config/references/preferences-schema.md):
.arness/workflow.local.yaml — if the file exists and pipeline.expert-debate is present, use that value and note source.~/.arness/workflow-preferences.yaml — if the file exists and pipeline.expert-debate is present, use that value and note source.Branch on the resolved value:
If standard: Show status line: "Preference: standard spec, no expert debate ([source])". Auto-proceed to Skill: arn-code:arn-code-feature-spec.
If auto: Only propose expert debate when the scope router score is 16 or higher (top-quartile complexity). If score is 16+, present the expert debate gate below. If score is below 16, show status line: "Preference: standard spec (auto mode, score [N] below expert-debate threshold of 16) ([source])". Auto-proceed to Skill: arn-code:arn-code-feature-spec.
If ask: Present the expert debate gate below (when scope router total was 16+). If score is below 16, proceed directly to Skill: arn-code:arn-code-feature-spec (expert debate is not applicable at lower scores). Do NOT show the "remember this?" follow-up.
If null (or invalid value): Present the expert debate gate below (when scope router total was 16+). If score is below 16, proceed directly to Skill: arn-code:arn-code-feature-spec. After the user answers, show the "remember this?" follow-up (see below).
Gate (shown when scope router total is 16+ and value is auto with score 16+, ask, null, or invalid):
Ask (using AskUserQuestion):
"This is a significant feature. How would you like to develop the specification?"
Options:
If Standard feature spec: Skill: arn-code:arn-code-feature-spec
If Expert debate: Skill: arn-code:arn-code-feature-spec-teams
Follow-up (only when preference was null and the gate was shown): After the user answers, ask:
Ask (using AskUserQuestion):
"Should Arness remember this choice for future sessions?"
Options:
standard to preferences)auto to preferences)If Yes (standard): Write standard to ~/.arness/workflow-preferences.yaml under pipeline.expert-debate. Create ~/.arness/ directory and file if they do not exist. If the file already exists, read it first, add or update the key under pipeline:, and write back preserving all existing keys.
If Yes (auto): Write auto to ~/.arness/workflow-preferences.yaml under pipeline.expert-debate (same write logic).
If No: Write ask to ~/.arness/workflow-preferences.yaml under pipeline.expert-debate (same write logic).
After spec completes, proceed to G3.
Show progress:
Planning [thorough]: entry -> scope-router -> SPEC -> plan -> save -> review-plan -> taskify -> [ready]
^^^^
Preference check: Read pipeline.spec-review using the two-tier lookup chain (see ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-ensure-config/references/preferences-schema.md):
.arness/workflow.local.yaml — if the file exists and pipeline.spec-review is present, use that value and note source as "project override in workflow.local.yaml".~/.arness/workflow-preferences.yaml — if the file exists and pipeline.spec-review is present, use that value and note source as "stored in workflow-preferences.yaml".Branch on the resolved value:
If review: Show status line: "Preference: reviewing spec ([source])". Auto-proceed to spec review — read the spec file and present a summary (problem statement, key requirements, architectural approach, open items). Allow edits. When satisfied, continue to Step 6.
If proceed: Show status line: "Preference: proceeding to plan ([source])". Auto-proceed to Step 6 (Plan Generation).
If upload: Check if Issue tracker is none. If none, fall through to the gate below — show the gate but do NOT show the "remember this?" follow-up (the user already has a stored preference; it is just inapplicable in this project because no issue tracker is configured. Do not modify the stored preference). If Issue tracker is not none: show status line "Preference: uploading as issue ([source])". Auto-proceed to Skill: arn-code:arn-code-create-issue with the spec content. After issue is created, exit planning.
If ask: Present the gate below. Do NOT show the "remember this?" follow-up afterward.
If null (or invalid value): Present the gate below. After the user answers, show the "remember this?" follow-up (see below).
Gate (shown when value is ask, null, or invalid):
Ask (using AskUserQuestion):
"Spec ready. What next?"
Options:
none)If Review spec: Read the spec file and present a summary (problem statement, key requirements, architectural approach, open items). Allow edits. When satisfied, re-present G3.
If Proceed to plan: Continue to Step 6 (Plan Generation).
If Upload as issue: Skill: arn-code:arn-code-create-issue with the spec content. After issue is created, exit planning. "Issue created. Run /arn-planning when ready to plan the implementation."
Follow-up (only when preference was null): After the user answers the gate, ask:
Ask (using AskUserQuestion):
"Should Arness remember this choice for future sessions?"
Options:
If Yes: Write the chosen value (review, proceed, or upload) to ~/.arness/workflow-preferences.yaml under pipeline.spec-review. Create ~/.arness/ directory and file if they do not exist. If the file already exists, read it first, add or update the key under pipeline:, and write back preserving all existing keys.
If No: Write ask to ~/.arness/workflow-preferences.yaml under pipeline.spec-review (same write logic).
Show progress:
Planning [thorough]: entry -> scope-router -> spec -> PLAN -> save -> review-plan -> taskify -> [ready]
^^^^
Derive the spec name from the spec filename (e.g., FEATURE_websocket-notifications.md → websocket-notifications) and invoke the plan skill:
Skill: arn-code:arn-code-plan <spec-name>
The plan skill has its own feedback loop — the user iterates with the planner agent until the plan is approved. When it completes, a PLAN_PREVIEW_<spec-name>.md file exists in the plans directory.
Show progress:
Planning [thorough]: entry -> scope-router -> spec -> plan -> SAVE -> review-plan -> taskify -> [ready]
^^^^
Inform: "Plan approved. Converting to structured project..."
Skill: arn-code:arn-code-save-plan
Save-plan auto-detects the PLAN_PREVIEW file and creates the project structure (INTRODUCTION.md, phase plans, TASKS.md, PROGRESS_TRACKER.json).
Show progress:
Planning [thorough]: entry -> scope-router -> spec -> plan -> save -> REVIEW-PLAN -> taskify -> [ready]
^^^^^^^^^^^
Preference check: Read pipeline.plan-review using the two-tier lookup chain (see ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-ensure-config/references/preferences-schema.md):
.arness/workflow.local.yaml — if the file exists and pipeline.plan-review is present, use that value and note source.~/.arness/workflow-preferences.yaml — if the file exists and pipeline.plan-review is present, use that value and note source.Branch on the resolved value:
If review: Show status line: "Preference: reviewing plan before execution ([source])". Auto-proceed to Skill: arn-code:arn-code-review-plan. After review completes, proceed to Step 9.
If skip: Show status line: "Preference: skipping plan review ([source])". Auto-proceed to Step 9 (Taskify).
If ask: Present the gate below. Do NOT show the "remember this?" follow-up afterward.
If null (or invalid value): Present the gate below. After the user answers, show the "remember this?" follow-up (see below).
Gate (shown when value is ask, null, or invalid):
Ask (using AskUserQuestion):
"The structured plan has been created. Review it before execution?"
Options:
If Review plan: Skill: arn-code:arn-code-review-plan
If Skip: Proceed to Step 9.
Follow-up (only when preference was null): After the user answers the gate, ask:
Ask (using AskUserQuestion):
"Should Arness remember this choice for future sessions?"
Options:
If Yes: Write the chosen value (review or skip) to ~/.arness/workflow-preferences.yaml under pipeline.plan-review. Create ~/.arness/ directory and file if they do not exist. If the file already exists, read it first, add or update the key under pipeline:, and write back preserving all existing keys.
If No: Write ask to ~/.arness/workflow-preferences.yaml under pipeline.plan-review (same write logic).
Show progress:
Planning [thorough]: entry -> scope-router -> spec -> plan -> save -> review-plan -> TASKIFY -> [ready]
^^^^^^^
Inform: "Creating task list..."
Skill: arn-code:arn-code-taskify
Taskify converts TASKS.md into Claude Code tasks with dependency management.
Show progress:
Planning [thorough]: entry -> scope-router -> spec -> plan -> save -> review-plan -> taskify -> [READY]
^^^^^
Ask (using AskUserQuestion):
"Planning complete. Your plan is structured and tasks are created. Start implementing?"
Options:
/arn-implementing when ready)If Start implementing: Skill: arn-code:arn-implementing
If Not yet: Exit with: "Run /arn-implementing when ready to start building."
Sketch is invoked from within arn-code-feature-spec during the spec exploration phase — not at the planning level. When a feature involves UI and ui-patterns.md has a ## Sketch Strategy section, the feature-spec skill proactively offers sketch to the user during the spec conversation.
No action is needed from arn-planning to manage sketch — it is fully delegated to the spec skill.
## Arness config missing: Handled by Step 0 (ensure-config) — this should not occur if Step 0 completed successfully./arn-shipping or exit./arn-implementing with the selected tier intent. Exit planning.arn-code-feature-spec./arn-planning again to resume — artifact detection will pick up where you left off."