Getting Started

SpecArk is a plugin bundle for Structured Prompt-Driven Development that works with both Codex and Claude Code. This page is the fastest path to a first successful run.

Before you start

You are in the right place if you want:

• a repeatable path from idea or requirement to implementation
• file-backed artifacts between phases
• an explicit skill surface instead of vague prompting
• a clear handoff from one phase to the next

If you only need installation details, jump to Codex install or Claude install.

Step 1: Install

Codex

codex plugin marketplace add maxgda/spec-ark
codex plugin marketplace upgrade

Claude Code

claude plugin marketplace add maxgda/spec-ark
claude plugin install specark

See Claude Code Installation for full details and verification steps.

After install

• The spdd-* skills are available in your session.
• You are ready to give the workflow a real input artifact.

Step 2: Pick the right first command

Most first-time users should start with the orchestrator:

Codex

Use the spdd-orchestrator skill on @idea-of-the-enhancement.md in semi-auto mode.

Claude Code

/specark:spdd-orchestrator @idea-of-the-enhancement.md semi-auto

Use a manual phase only when you already have the matching artifact:

Your artifact	Start phase
Rough idea missing problem, user, outcome, or scope context	spdd-discovery
Broad idea or noisy PRD with enough context to slice	spdd-plan → spdd-story
Broad requirement	spdd-story
Focused story or requirement	spdd-analysis
Analysis artifact in spdd/analysis/	spdd-reasons-canvas
Prompt artifact in spdd/prompt/	spdd-generate

Good signal

• You are not forcing a broad idea into spdd-generate.
• Your command matches the artifact you actually have.
• The workflow starts from the smallest valid phase instead of repeating context.

Step 3: Watch the artifact handoff

SpecArk works best when each phase creates a file that becomes the next phase's input.

idea.md
  └─ spdd/discovery/DISCOVERY.md     ← spdd-discovery (optional, manual)
       └─ requirements/STORY-001.md  ← spdd-story
            └─ spdd/analysis/ANALYSIS.md  ← spdd-analysis
                 └─ spdd/prompt/PROMPT.md ← spdd-reasons-canvas
                      └─ implementation   ← spdd-generate
                           └─ spdd/tests/ ← spdd-api-test (optional)

Good signal

• Each step leaves behind a repository file.
• The next command points at that file instead of pasting the same context again.
• You can inspect the artifact before moving forward.

Step 4: Know when to choose orchestrator vs manual flow

Choose the orchestrator when:

• the requirement is broad
• you want review gates between phases
• you are still learning the workflow

Choose manual phase entry when:

• you already have the correct artifact for the next phase
• you want a narrow, single-purpose request
• you are resuming work after a previous phase already completed

Step 5: Continue into your first feature

Once installation and the first artifact flow make sense, use the full end-to-end walkthrough:

• First Feature Tutorial

That tutorial covers:

• install through first implementation
• expected output after each step
• lightweight git guidance on branches, commits, and worktrees
• how to hand the feature off for release-ready review

Common mistakes

Avoid these

• Starting with spdd-generate before a prompt exists in spdd/prompt/.
• Re-pasting the full requirement into every phase instead of passing the produced artifact.
• Treating README, getting started, and workflow reference pages as interchangeable.
• Mixing maintainer-only local plugin work with the first-time adopter path.

Read next

1. First Feature Tutorial
2. Workflow Overview
3. Phase Handoffs
4. Skill Index