{
  "markdown": "# ALPS Writer Plugins\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n\nA Codex and Claude Code **marketplace** that ships two independent plugins for spec-driven development: **alps-writer** (PRD authoring) and **adr-writer** (ADR-driven cycle). Both install from the marketplace alone — **no npm, no npx, no build step** for end users. The alps-writer MCP server is bundled (dependencies inlined) and committed at `plugins/alps-writer/dist/`.\n\n| Plugin                  | Scope                                                                                                                          | Depends on                       |\n| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- |\n| **`alps-writer`** (PRD) | Write Full ALPS or lightweight mockup/PoC product documents conversationally. Bridges Full ALPS Section 7 features to ADRs.    | adr-writer (only for the bridge) |\n| **`adr-writer`** (ADR)  | ADR-driven development: author, implement, adversarially review, and sync; an ADR-first hook runs when session context starts. | nothing — fully standalone       |\n\nThe two are split so that **adr-writer never references ALPS**. The only coupling is one-way (`alps-writer → adr-writer`): `/feature-to-adr` transfers each implementable Feature's complete contract into one or several ADRs. After handoff the PRD remains a legacy planning document; explicit re-import compares it with authoritative ADRs and applies only approved semantic changes.\n\n## A removable, non-invasive harness\n\nThe plugins are management harnesses, not an additional authority layer. Product\nintent remains in PRDs, admitted architecture decisions and requirement\ncontracts remain in ADRs, implementation truth remains in code and tests, and\nrepository conventions remain in README/AGENTS/CONTRIBUTING. Removing either\nplugin leaves those artifacts readable and useful to a future model without\nhidden plugin state.\n\nSkills and hooks constrain observable artifacts, external actions, evidence,\napproval boundaries, and Status transitions. They do not require private\nchain-of-thought or prescribe how a model must internally reason. The active\nmodel chooses action-level orchestration—whether to use no subagent, one, or\nseveral; named or generic agents; parallel or sequential execution; and the\navailable model for each role—while preserving the same user-visible workflow.\nComprehension-load behavior, dependency gates, risk-selected reviews, Evidence\nPackages, and completion rules remain stable regardless of that orchestration.\n\n## The core rule: preserve reproducible conditions, not recoverable facts\n\nThe system persists only information whose loss would make a future\nimplementation violate human intent, an admitted decision, or a requirement.\nIt does not persist a second copy of facts that an agent can recover by reading\ncode, tests, dependency metadata, or deterministic tool output.\n\nApply the tests in this order:\n\n1. **Requirement gate** — if the fact disappeared, could regenerated code violate\n   a required value, state, permission, ordering rule, failure guarantee,\n   boundary, or success condition? If yes, preserve it at the level that owns\n   the contract.\n2. **Code-readthrough test** — if the fact is not a requirement and an agent can\n   recover it from the implementation, leave it in code and tests.\n3. **ADR admission gate and litmus test** — if code cannot explain why one\n   durable alternative was adopted and changing the fact would change the\n   architectural decision, preserve the decision, rationale, trade-off, and\n   decision-changing assumptions in an ADR.\n\n“Reproducible” does not mean recreating the same files, functions, libraries, or\nmodule layout. It means a different implementation can be generated while still\nhonoring the same observable product behavior and architectural constraints.\n\n| Level             | Persist                                                                                                                                    | Do not persist                                                               |\n| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |\n| ALPS PRD          | user problem, observable outcomes, product contracts, success conditions, explicit non-goals, durable system constraints                   | code paths, stack inventories, implementation plans, copied tickets/logs     |\n| ADR               | admitted decision, exact requirement contract, rationale, alternatives, durable boundaries, implementation-independent observable evidence | libraries, SDKs, signatures, field tables, tuning values, internal call flow |\n| Code and tests    | implementation structure, identifiers, dependencies, tuning, enforcement, executable verification                                          | PRD or ADR back-references                                                   |\n| Issue, PR, commit | change-specific intent and verbatim history                                                                                                | a competing source of product or architecture truth                          |\n\nPlans, search results, mapping snapshots, approval views, reviewer transcripts,\neval results, and derived evidence packages stay disposable because the\nauthoritative artifacts can reproduce them.\n\n## What is ALPS?\n\n**ALPS** (Agentic Lean Product Spec) is a PRD format built for agentic development. A traditional PRD assumes a human reader who fills in gaps from intuition; ALPS assumes an AI agent that needs an unambiguous specification to write reliable code.\n\nIt fixes the format (9 sections, explicit dependencies, vertical-slice features) and inverts the authoring loop: the **agent asks focused questions, the human answers**, with no section saved without confirmation. Out of Scope is a first-class section so the agent knows what _not_ to build.\n\n**Lite ALPS** is a 4-section working-backwards simplification of Full ALPS for planners and PMs defining a minimum PoC. The user first confirms the target problem and Desired Business Impact; AI then proposes the minimum solution, a product-level C4 Context diagram, Essential User Experiences, and a concrete executable Demo Scenario for approval. Unwritten optional scope is omitted from Markdown. Lite and Full keep independent files, state, and completion.\n\nSee [`about-alps.md`](./plugins/alps-writer/templates/alps/about-alps.md) for the full design rationale and how ALPS feeds into the ADR-driven cycle.\n\n## Quick Start\n\nRegister this repository as a marketplace, then install whichever plugins you want. They are independent — install one or both.\n\n**Codex**\n\n```bash\ncodex plugin marketplace add haandol/alps-writer-plugins\ncodex plugin add alps-writer@alps-writer\ncodex plugin add adr-writer@alps-writer\n```\n\nInvoke skills with `$alps-init`, `$lite-alps-init`, `$feature-to-adr`, `$adr-new`, `$adr-impl`, `$adr-impl-refactor`, `$adr-impl-review`, `$adr-review`, `$adr-sync`, and `$adr-rollup`, or ask for the workflow in natural language. On first use, review and trust ADR Writer's single `SessionStart` hook when Codex prompts you. It restores context on startup, resume, clear, and compaction; it does not run for every user prompt.\n\n**Claude Code**\n\n```\n/plugin marketplace add haandol/alps-writer-plugins\n/plugin install alps-writer@alps-writer   # PRD authoring (/alps-init, /lite-alps-init, /feature-to-adr)\n/plugin install adr-writer@alps-writer    # ADR cycle (/adr-new, /adr-impl, /adr-impl-refactor, /adr-impl-review, /adr-review, /adr-sync, hooks)\n```\n\n> `/feature-to-adr` (in alps-writer) delegates ADR authoring to `/adr-new` (in adr-writer), so install **both** if you want the ALPS → ADR bridge. adr-writer on its own works without any ALPS PRD.\n\nThree independent entry flows, driven by `$skill-name` in Codex or `/skill-name` in Claude Code:\n\n- **PoC authoring** — `/lite-alps-init` → minimum PoC scope and demo\n- **PRD-first** — `/alps-init` → `/feature-to-adr` → `/adr-impl` → `/adr-impl-refactor` (automatic) → `/adr-impl-review` (completion gate) → `Accepted`\n- **ADR-only** — `/adr-new` → `/adr-impl` → `/adr-impl-refactor` (automatic) → `/adr-impl-review` (completion gate) → `Accepted`\n\nLite ALPS reuses Full ALPS's conversation-led authoring behavior but keeps an independent document lifecycle. Neither reads, updates, converts into, or shares completion state with the other.\n\nRun `/adr-sync` when review finds implementation-fact drift, after broad refactors or manual ADR edits, or as a periodic audit; it is not a mandatory deep scan after every small implementation.\n\nSee the [Usage guide](./docs/usage.md) for the full cycle, walkthroughs, slash commands, hook behavior, and the mapping file, or the [ADR process overview](./docs/adr-process.md) for the same cycle drawn as diagrams.\n\nCodex users on Amazon Bedrock should disable multi-agent before running ADR review skills; see [ADR Writer troubleshooting](./plugins/adr-writer/README.md#amazon-bedrock-rejects-a-subagent-request).\n\n## Features\n\n**alps-writer (PRD)**\n\n- 9-section ALPS (PRD) template with structured XML templates, conversation guides, durable architecture constraints, and per-Feature demos connected to the end-to-end demo scenario\n- 4-section Lite ALPS template that starts from Desired Business Impact and has AI propose the minimum solution, one product-level C4 Context, Essential User Experiences, and executable demo\n- Interactive Q&A workflow — atomic confirmation by default, with explicit batch approval for complete structured input\n- Contract-complete plain-text approval digests — concise raw-text views preserve every requirement value and rule before subsection-level persistence\n- Document management — create, save, load, and export as clean Markdown\n- Section dependency tracking — ensures referenced sections are reviewed first\n- **Disposable comprehension signal** — Section 7 Features use a calibrated `1–10` scale with `4–6` as the recommended range; Features at `8/10` or higher receive up to three non-blocking user-behavior split candidates\n- **First-reader-friendly Feature specs** — Section 7 explains unfamiliar terms for junior developers and recommends optional Mermaid diagrams, preferring `sequenceDiagram` when multi-participant data flow is clearer visually\n- **ALPS → ADR ownership handoff** — `/feature-to-adr` transfers every implementation-relevant Feature contract into `1..N` real ADRs, leaves replaceable means to code, and makes equivalent explicit re-imports no-ops\n- Works with Claude Desktop, Claude Code, Cursor, Kiro, and any MCP-compatible client (MCP server only)\n\n**adr-writer (ADR)**\n\n- **ADR-driven development cycle** — author ADRs directly with `/adr-new`, implement them with `/adr-impl`, and keep them in sync with `/adr-sync`\n- **Domain-aware gap resolution** — `/adr-impl` derives obligations already implied by the contract, reuses established project/domain defaults for reversible implementation choices, and packages only real product-policy gaps as one recommendation-led Decision request\n- **Searchable implementation documentation and executable cases** — `/adr-impl` requires language-standard why/how comments for changed functions, reuses contract terminology without citing ADR files, and tests both the ideal path and relevant edge cases\n- **Junior-readable review reports** — document, sync, implementation, and refactor reviews lead with verdict, impact, action, and risk, explain unfamiliar terms once, preserve exact evidence below, and use grounded Mermaid for multi-participant, state, dependency, data, and failure flows. Implementation-review HTML adds a table of contents, renders the narrative and Mermaid relationships, shows findings before detailed evidence, and collapses proven coverage, scope, metrics, choices, and comprehension by default\n- **Disposable comprehension signal** — ADR digests, implementation plans, and document reviews show only an ephemeral `1–10` score from an internal five-axis assessment; the score never becomes an ADR field or workflow gate\n- **Requested Stacked PR fallback** — when one Feature and ADR must stay intact, `/adr-impl` can offer dependency-ordered PR layers with one review question each; it never creates a Stack from the score alone\n- **ADR admission gate** — record durable requirement/architecture decisions while leaving replaceable libraries, SDKs, frameworks, and credential/auth wiring at the code level\n- **Verified implementation refactoring** — before Status promotion, independently review efficiency, complexity, coupling, duplication, and proportionate reuse; immediately apply only local behavior-preserving changes with before/after tests and propose the rest\n- **Implementation and Review Hiking** — ADR implementation and review use the same low vertical Hills. Each Hill is a user flow, logical capability, or evidence-grounded bounded context—not a technical layer, file group, or lifecycle phase. The implementation records its contract, cross-layer behavior, targeted test command, and observed result before moving on. The review uses reading zooms: Context for intent/contracts/scope, Container/Hill for a vertical capability, Component for detailed implementation, and collapsed Code for a focused diff or current excerpt. Every ADR contract appears in exactly one Hill. Localized implementations use a sufficiency perspective, while protected-surface or broad implementations add separately grounded necessity/sufficiency perspectives. The ordinary main-session completion response never prints Q1 or starts grading.\n- **Provider-aware review fallback** — Codex sessions on Amazon Bedrock avoid unsupported subagent dispatch and retries; reviews continue through available model-selected paths while preserving the same evidence and refactor safety gates\n- **Model-selected review orchestration** — review perspectives and evidence are contractual, while subagent count, named/generic/main-session execution, parallelism, and model selection remain disposable choices made from current capability and risk\n- **ADR-first hook** — one `SessionStart` hook runs only on startup, resume, clear, and compaction recovery, injecting the admission-aware directive without mapping contents; admitted work reads `docs/adr/.mapping.json` before coding\n- Fully standalone — no ALPS PRD required\n\n## Documentation\n\n- [Usage guide](./docs/usage.md) — development cycle, walkthroughs, slash commands, hook, mapping file\n- [ADR process overview](./docs/adr-process.md) — the lifecycle, critical command paths, routing, and efficiency review as diagrams (Korean)\n- [Dependency model](./docs/dependency-model.md) — how PRD → ADR → code stay decoupled (the design core)\n- [MCP server](./docs/mcp-server.md) — run the alps-writer MCP server in other clients, env vars, tool reference\n- [`about-alps.md`](./plugins/alps-writer/templates/alps/about-alps.md) — ALPS format design rationale\n- [ADR templates](./plugins/adr-writer/templates/adr/) — authoring rules, directory structure, mapping schema\n\n## Repository layout\n\n```\nalps-writer-plugins/                 # marketplace root (this repo)\n├── .agents/plugins/marketplace.json # Codex marketplace\n├── .claude-plugin/marketplace.json  # Claude Code marketplace\n├── docs/                            # usage, dependency model, MCP server guides\n└── plugins/\n    ├── alps-writer/                 # PRD plugin (bundles its own MCP server)\n    │   ├── .codex-plugin/plugin.json    # Codex metadata + MCP registration\n    │   ├── .claude-plugin/plugin.json   # Claude Code metadata + MCP registration\n    │   ├── .mcp.json                    # Codex MCP server command\n    │   ├── src/                     # MCP server source (TypeScript)\n    │   ├── dist/                    # committed bundle (index.js + assets) — runs as-is\n    │   ├── skills/                  # /alps-init, /lite-alps-init, /feature-to-adr\n    │   └── templates/alps/\n    └── adr-writer/                  # ADR plugin (standalone, ALPS-agnostic)\n        ├── .codex-plugin/plugin.json\n        ├── .claude-plugin/plugin.json\n        ├── skills/                  # /adr-new, /adr-impl, /adr-impl-refactor, /adr-impl-review, /adr-review, /adr-sync, /adr-rollup\n        ├── agents/                  # ADR authoring + isolated refactor/implementation review roles\n        ├── hooks/                   # ADR-first directive hook (SessionStart)\n        └── templates/adr/           # README + concepts + authoring-rules + structure + mapping.schema.json\n```\n\n## Development\n\nThis is a pnpm workspace. The MCP server lives in `plugins/alps-writer/`; root scripts proxy to it.\n\n```bash\npnpm install        # Install dependencies (whole workspace)\npnpm build          # Bundle the alps-writer MCP server into plugins/alps-writer/dist/\npnpm lint           # ESLint the MCP server\npnpm format         # Prettier across the repo\n\n# Or work inside the package directly:\npnpm --filter alps-writer dev     # Run with tsx (watch mode)\npnpm --filter alps-writer start   # Run the built bundle\n```\n\n> **The bundle is committed.** `plugins/alps-writer/dist/` is checked into git (esbuild output with dependencies inlined) so the plugin runs from a marketplace install with no build step. **Whenever you change `src/`, run `pnpm build` and commit the regenerated `dist/`.**\n\nSee [AGENTS.md](./AGENTS.md) for the full architecture, code style, and conventions.\n\n## Contributing\n\nContributions are welcome. Before opening a PR, read [`CONTRIBUTING.md`](./CONTRIBUTING.md) for commit convention (Conventional Commits), branch naming, and code style. Open an issue first for substantial changes, make sure `pnpm lint` and `pnpm format:check` pass, and keep commits atomic.\n\nBug reports and feature requests: [GitHub Issues](https://github.com/haandol/alps-writer-plugins/issues).\n\n## License\n\n[MIT](./LICENSE)\n",
  "bytes": 18154,
  "sha": "6caaf99d23907514d9501179da162f8e4fd875cb84c28d6f1985bc663b769800",
  "repo_slug": "haandol/alps-writer-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_haandol_alps_writer_mcp_alps_writer_22771d72/readme"
}