{ "markdown": "

\n \n \n \"SpecArk\"\n \n

\n\n# SpecArk\n\nStructured Prompt-Driven Development, packaged as a Git-distributed plugin bundle for **Codex**, **Claude Code**, and **Claude Cowork**.\n\nSpecArk turns SPDD into an explicit, artifact-driven workflow instead of a loose series of prompts. It helps you move from discovery intake or a requirement to analysis, prompt generation, implementation, and optional verification by handing repository files from one phase to the next.\n\nUse it when your repository needs a repeatable path from broad request to implementation without re-pasting the same context at every step.\n\n## Start Here\n\n### Codex — two-command startup\n\n```bash\ncodex plugin marketplace add maxgda/spec-ark\ncodex plugin marketplace upgrade\n```\n\n### Claude Code & Cowork — two-command startup\n\n```bash\nclaude plugin marketplace add maxgda/spec-ark\nclaude plugin install specark\n```\n\nWorks in both Claude Code (CLI) and Claude Cowork (desktop). One install covers both.\n\n### First real run\n\n**Codex** — starting from a broad idea:\n\n```text\nUse the spdd-orchestrator skill on @idea-of-the-enhancement.md in semi-auto mode.\n```\n\n**Claude Code** — starting from a broad idea:\n\n```text\n/specark:spdd-orchestrator @idea-of-the-enhancement.md semi-auto\n```\n\nIf you already know the exact artifact you have, jump to the matching phase:\n\n```text\n# Codex\nUse the spdd-analysis skill on @requirements/STORY-001.md.\n\n# Claude Code\n/specark:spdd-analysis @requirements/STORY-001.md\n```\n\n## Why SpecArk\n\n- explicit `spdd-*` skills instead of ambiguous routing\n- file-backed handoffs between workflow phases\n- narrower prompts and lower token burn\n- clean recovery paths when requirements or code drift\n- an optional orchestrator when you want one command surface\n\n## Use SpecArk When\n\n- you want a repeatable path from idea to implementation\n- you prefer repository files over re-pasting the same context in chat\n- you need prompt updates after requirement changes\n- you need prompt sync after refactors or implementation drift\n- you want clear phase boundaries instead of free-form prompting\n\n## What Happens Next\n\nThe normal SPDD flow is:\n\n0a. optional manual `spdd-discovery` for unclear early context\n0b. optional manual `spdd-plan`\n1. `spdd-story`\n2. `spdd-analysis`\n3. `spdd-reasons-canvas`\n4. `spdd-generate`\n5. `spdd-api-test` when API verification assets are needed\n\nExpected project-local artifact folders:\n\n- `spdd/discovery/`\n- `spdd/plan/`\n- `requirements/`\n- `spdd/analysis/`\n- `spdd/prompt/`\n- `spdd/tests/`\n\nThese artifacts belong to the consuming project, not the plugin itself.\n\n## First 10 Minutes\n\n1. Install with the marketplace commands above (Codex or Claude Code).\n2. Run the orchestrator if you are starting broad, or jump straight to the phase that matches your current artifact.\n3. Review the produced artifact before moving forward to the next phase.\n4. Continue into the implementation prompt and generated code.\n\nFor a guided walkthrough, start with [Getting Started](docs/getting-started.md) and then use the [First Feature Tutorial](docs/first-feature.md).\n\n## Keep Token Usage Low\n\nThe cheapest SPDD workflow is the one that keeps every request narrow and artifact-driven.\n\n### Recommended pattern\n\n```text\nUse the spdd-story skill on @idea.md.\nUse the spdd-analysis skill on @requirements/STORY-001.md.\nUse the spdd-reasons-canvas skill on @spdd/analysis/ANALYSIS-001.md.\nUse the spdd-generate skill on @spdd/prompt/PROMPT-001.md.\n```\n\n### Anti-pattern\n\n```text\nHere is the full requirement again...\nHere is the architecture again...\nHere is the analysis again...\nNow generate everything end to end and also update tests.\n```\n\n## Local Development And Docs\n\nFor local plugin work:\n\n1. Keep the plugin at `plugins/specark/`.\n2. Keep the marketplace file at `.agents/plugins/marketplace.json`.\n3. Restart Codex after changing skills, references, or plugin metadata.\n\nValidate the bundle:\n\n```bash\npython3 plugins/specark/scripts/validate_plugin_bundle.py\n```\n\nRun the docs site locally:\n\n```bash\nnpm install\nnpm run docs:dev\n```\n\nOther useful docs commands:\n\n```bash\nnpm run docs:build\nnpm run docs:preview\n```\n\n## Included Skills\n\n- `spdd-orchestrator`: coordinate the workflow across phases and review gates\n- `spdd-discovery`: run a Discovery Interview and write a Discovery Brief before planning, story splitting, or analysis\n- `spdd-plan`: turn broad product direction into ordered delivery slices before story generation\n- `spdd-story`: split a broad requirement into implementation-sized stories\n- `spdd-analysis`: turn a story or requirement into strategic engineering context\n- `spdd-reasons-canvas`: generate the implementation-ready REASONS prompt\n- `spdd-generate`: implement code from the prompt\n- `spdd-prompt-update`: update an existing prompt after requirement or design changes\n- `spdd-sync`: sync implementation reality back into the prompt\n- `spdd-api-test`: generate or refresh API-oriented verification assets\n- `spdd-doc-sync`: sync human-facing in-repo documentation after behavior or workflow changes\n- `spdd-session-health`: check session health before heavy phase invocation\n\n## Canonical Sources\n\nSource-of-truth workflow text is split by provenance:\n\n- `plugins/specark/references/source-commands/` for upstream SPDD command text copied from `open-spdd`\n- `plugins/specark/references/local-commands/` for SpecArk-authored command contracts such as `spdd-orchestrator`, `spdd-discovery`, and `spdd-plan`\n\nProvenance metadata for copied upstream commands lives in `plugins/specark/references/source-commands/SOURCES.md`.\n\n## Credits & Prior Art\n\nSpecArk is a Codex / Claude Code / Cowork packaging of an existing methodology. It does not invent SPDD or the REASONS Canvas.\n\n- **Methodology — Structured-Prompt-Driven Development (SPDD) and the REASONS Canvas:** authored by **Wei Zhang** and **Jessie Jie Xia** (Thoughtworks). See [\"Structured-Prompt-Driven Development\"](https://martinfowler.com/articles/structured-prompt-driven/) on martinfowler.com (28 April 2026).\n- **Reference implementation — canonical phase commands:** the files under [`plugins/specark/references/source-commands/`](plugins/specark/references/source-commands/) are copied verbatim from [`gszhangwei/open-spdd`](https://github.com/gszhangwei/open-spdd) and remain under that project's MIT license (© 2026 gszhangwei). Per-file provenance is in [SOURCES.md](plugins/specark/references/source-commands/SOURCES.md); the full upstream notice is reproduced in [LICENSE-THIRD-PARTY.md](LICENSE-THIRD-PARTY.md).\n\nSpecArk itself is MIT-licensed — see [LICENSE](LICENSE).\n\n## Read More\n\n- [Getting Started](docs/getting-started.md)\n- [First Feature Tutorial](docs/first-feature.md)\n- [Installation](docs/installation.md)\n- [Workflow Overview](docs/workflow/index.md)\n- [Skill Index](docs/skills/index.md)\n- [Limitations](docs/limitations.md)\n- [Next Steps](docs/next-steps.md)\n- [Release Notes](docs/release-notes.md)\n- [Maintainer Notes](docs/maintainer-notes.md)\n", "bytes": 7158, "sha": "10704eee2d2f8527ffa863aa8cd6d1b88e3015e107508d1a9e8995d946891ce7", "repo_slug": "maxgda/spec-ark", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_maxgda_spec_ark_spec_ark_463bdeba/readme" }