arn-code-help

Arness Help

Detect the user's current position in the Arness workflow pipeline, render an ASCII diagram with the active stage marked, and suggest the next command to run. Supports cross-plugin awareness — detects activity in Arness Spark and Arness Infra and provides hints at the bottom of the output. This skill is strictly read-only -- it never modifies files or project state.

Allowed tools: Read, Glob, Grep only. This skill MUST NOT use Write, Edit, Bash, or Task tools. This skill MUST NOT invoke any agents.

Workflow

Step 0: Multi-Plugin Awareness

1. From the ## Arness section (loaded in Step 1), detect other plugin field groups:
   • spark_fields_present: true if Vision directory OR Use cases directory OR Prototypes directory present
   • infra_fields_present: true if Infra plans directory OR Infra specs directory present
2. For each detected plugin, do a quick existence check (max 2 files):
   • Spark: Check if <Vision directory>/product-concept.md exists
   • Infra: Check if <Infra plans directory> has any subdirectories, OR if Dockerfile or docker-compose.yml exists in the project root
3. Record { plugin_name, has_activity: bool } for each detected plugin.
4. Proceed to Step 1. Cross-plugin hints are appended AFTER own status is rendered in Step 3.

---

Step 1: Load Configuration

1. Read the project's CLAUDE.md file.
2. Extract the ## Arness section.
3. From the ## Arness section, extract core fields:
   • Plans directory (e.g., .arness/plans/)
   • Specs directory (e.g., .arness/specs/)
   • Docs directory (e.g., .arness/docs/)

If ## Arness is missing: Skip to Step 3 and render the core pipeline diagram with all stages unmarked. Suggest the user run /arn-planning to get started for an existing project, or /arn-brainstorming for a brand-new project (requires arn-spark). Do not attempt detection.

---

Step 2: Detect Pipeline Position

Read the pipeline reference file at ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-help/references/pipeline-map.md to load detection rules, context-aware rendering rules, and next-step tables.

Core Detection

Per-Project Detection

For each subdirectory in the plans directory, check artifacts to determine the most advanced stage. Check from most advanced to least advanced -- first match wins:

1. Documented (docs): A file matching the project name exists in the configured docs directory (<docs-dir>/<project>.md or <docs-dir>/<project>/ directory)
2. Execution complete (execute-done): The subdirectory has PROGRESS_TRACKER.json with overallStatus = "completed". Note: arn-code-review-implementation does not write a durable artifact, so both "execution complete" and "review complete" map to this detection. The next-step suggestion covers both cases.
3. Executing (execute): The subdirectory has any reports/IMPLEMENTATION_REPORT_*.json or reports/TESTING_REPORT_*.json
4. Tasks created (taskify): The subdirectory has TASKS.md with parseable task entries
5. Plan saved (save): The subdirectory has INTRODUCTION.md
6. Otherwise: skip this subdirectory (incomplete project setup)

Global Core Detection

If no per-project stages were detected:

• Check the plans directory for subdirectories matching SWIFT_* containing SWIFT_REPORT.json -- if found, stage is Swift complete (swift-complete)
• Check the plans directory for subdirectories matching SWIFT_* containing SWIFT_*.md but no SWIFT_REPORT.json -- if found, stage is Swift in progress (swift-in-progress)
• Check the plans directory for subdirectories matching STANDARD_* containing STANDARD_REPORT.json -- if found, stage is Standard complete (standard-complete)
• Check the plans directory for subdirectories matching STANDARD_* containing STANDARD_*.md but no STANDARD_REPORT.json -- if found, stage is Standard in progress (standard-in-progress)
• Check the plans directory for files matching PLAN_PREVIEW_*.md -- if found, stage is Plan generated (plan)
• Check the specs directory for files matching FEATURE_*.md or BUGFIX_*.md -- if found, stage is Spec written (spec)
• Check the specs directory for files matching DRAFT_FEATURE_*.md -- if found and no finalized FEATURE_*.md or BUGFIX_*.md exists, stage is Spec in progress (spec-draft)
• If ## Arness exists with core fields but specs and plans directories are empty, stage is Initialized (init). Suggest /arn-code-feature-spec, /arn-code-bug-spec, for quick changes (1-8 files) /arn-code-swift, or for medium complexity /arn-code-standard

Fallback

• If ## Arness exists but no artifacts are found, stage is init.

---

Step 3: Render Pipeline Diagram

Read the pipeline templates and rendering rules from ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-help/references/pipeline-map.md.

Show the core pipeline diagram with the position marker. Follow the existing rendering:

• Single-project or multi-project diagrams
• Next-step suggestion from the core next-step table

After rendering the core pipeline status and next-step suggestion, append cross-plugin hints from Step 0:

• If Spark has activity: append "Spark exploration: active — run /arn-spark-help for details."
• If Infra has activity: append "Infrastructure pipeline: active — run /arn-infra-help for details."
• If own pipeline has NO activity but is initialized (init): show own suggestions FIRST (e.g., "Run /arn-code-feature-spec to spec a feature, /arn-code-bug-spec for a bug, /arn-code-swift for a quick fix, or /arn-code-assess for a codebase review"), then optionally mention other plugins.
• When own pipeline is complete (shipped): suggest "Start a new feature? /arn-planning". If Infra is configured: "Deploy with /arn-infra-wizard."

Keep output concise -- the user wants a quick status check, not a wall of text. Show the diagram, the detected stage, the next command, and any cross-plugin hints. That is all.

---

Step 4: Answer Follow-up Questions

After presenting the pipeline status:

1. Remain available for follow-up questions about either pipeline, skill purposes, or workflow decisions.
2. Reference ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-help/references/pipeline-map.md for answers -- do not re-scan the filesystem unless the user explicitly asks to refresh the detection.
3. Keep answers brief and direct.

Arness-sketch detection: If a arness-sketches/ directory exists in the project root, note it in the status output: "Active sketches: arness-sketches/ directory detected with [N] route(s)." This is informational -- it does not affect pipeline position.

Common questions the user might ask:

• "What does arn-code-taskify do?" -- explain the skill's purpose from the pipeline context
• "Can I skip the review step?" -- explain that steps are optional but recommended
• "How do I go back to the previous step?" -- explain that the pipeline is not strictly linear; the user can re-run any earlier skill
• "How do I start?" -- suggest /arn-planning which handles scope assessment and routes to the right workflow
• "How do I run the full pipeline?" -- explain the chaining pattern: /arn-planning → /arn-implementing → /arn-shipping. Each entry point offers to chain to the next at completion.
• "What are the entry points?" -- explain the 5 first-citizen entry points: /arn-planning, /arn-implementing, /arn-shipping, /arn-reviewing-pr, /arn-assessing
• "Where is greenfield status?" -- "Run /arn-spark-help for Spark exploration pipeline status."
• "Where is infrastructure status?" -- "Run /arn-infra-help for Arness Infra pipeline status."
• "What is arn-code-assess?" -- explain it's a comprehensive assessment tool that reviews the codebase against stored patterns, lets you prioritize findings, then orchestrates the full pipeline to implement improvements
• "Can I review my codebase quality?" -- suggest /arn-code-assess for a guided technical review with prioritized improvements
• "What is arn-code-simplify?" -- Reviews implemented code for reuse, quality, and efficiency improvements using three parallel reviewers with pattern awareness. Runs after execution and before review.
• "How do I simplify my code?" -- Run /arn-code-simplify after executing your plan or swift implementation. It auto-detects the scope from your most recent execution artifacts.

---

Error Handling

• ## Arness section not found in CLAUDE.md -- Show the core pipeline diagram with no stage marked. Display "Not configured" as the current position. Suggest running /arn-planning for existing projects, or /arn-brainstorming for a brand-new project (requires arn-spark).
• Plans directory does not exist -- Treat the project as being at the "Initialized" (init) stage for core. Suggest running /arn-code-feature-spec or /arn-code-bug-spec to create a specification (or /arn-code-feature-spec-teams for team debate format). For quick changes (1-8 files), suggest /arn-code-swift.
• Specs directory does not exist -- Treat the project as being at the "Initialized" (init) stage for core. Suggest running /arn-code-feature-spec or /arn-code-bug-spec. For quick changes (1-8 files), suggest /arn-code-swift.
• No projects found in plans directory -- Show the core pipeline at the global detection level. Check specs directory for spec files. If specs exist, mark the spec stage. Otherwise mark init.
• CLAUDE.md does not exist -- Same as ## Arness not found. Show core pipeline unmarked and suggest /arn-planning or /arn-brainstorming.
• Pipeline reference file not found -- Inform the user that the pipeline-map.md reference is missing and suggest reinstalling or updating the Arness plugin.

Constraints

• This skill MUST NOT write or modify any files.
• This skill MUST NOT invoke any agents.
• All tools used must be read-only: Read, Glob, Grep.
• All command suggestions must use bare skill names without the plugin prefix (e.g., /arn-code-init, /arn-code-plan, /arn-spark-discover). Do not use the fully qualified plugin:skill format in user-facing text.