arn-planning

Arness Planning

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.

Prerequisites: Ensure Configuration

Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-ensure-config/references/step-0-fast-path.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:

• Plans directory — for detecting plan previews and project folders
• Specs directory — for detecting specification files
• Code patterns — path to stored pattern documentation
• Issue tracker — determines if "Pick from backlog" option is available (github, jira, or none)

Workflow

Step 0: Input Routing

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) |

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?"

• Resume → skip to the detected resume point
• Start fresh → begin at G1 (do not delete existing artifacts)

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.

1. ## Arness config has a Vision directory field (only set by arn-spark-init, never by core arn-code-init)
2. If Vision directory exists, <vision-dir>/features/feature-backlog.md exists
3. The file contains a ## Feature Tracker table

If 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.

Step 2: Gate G1 — Entry Point

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:

1. Pick from backlog (Recommended) — Browse [unblocked] unblocked features from the greenfield pipeline
2. Batch plan ([unblocked] features) — Plan multiple features for parallel implementation
3. Describe a feature — Start with a new feature idea
4. Report a bug — Investigate a bug and develop it into a fix or spec

If unblocked <= 1 (no batch option — 3 options):

Options:

1. Pick from backlog (Recommended if [unblocked] > 0) — Browse [unblocked] unblocked features from the greenfield pipeline (shown when Issue tracker is not none OR greenfield backlog was detected — the greenfield backlog provides local-only browsing even without a remote issue tracker)
2. Describe a feature — Start with a new feature idea
3. Report a bug — Investigate a bug and develop it into a fix or spec

If no greenfield backlog (default):

Ask (using AskUserQuestion):

"What are you planning?"

Options:

1. Pick from backlog — Browse issues and pick one to work on (only shown if Issue tracker is not none)
2. Describe a feature — Start with a feature idea
3. Report a bug — Investigate a bug and develop it into a fix or spec

Based on choice:

• Pick from backlog → 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.
• Batch plan → 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.
• Describe a feature → Ask the user to describe the feature. Proceed to Step 3 with the description.
• Report a bug → Skill: arn-code:arn-code-bug-spec. Bug-spec handles its own investigation flow:
• If bug-spec resolves via simple path (fix applied, no spec): "Bug fixed. No planning needed." Offer: chain to /arn-shipping or exit.
• If bug-spec produces a spec file: proceed to G3 (Spec Review).

Step 3: Scope Assessment

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]
                   ^^^^^^^^^^^^

Step 3A: Read Codebase Context

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 patterns

Step 3B: Classify Intent

Analyze 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 f