Skip to content

nyssaai/plan-product

v0.12.9Apache-2.0

Define products, Ubiquitous Language glossaries, features, use cases, domain concepts, and dependency-ordered development plans through guided conversations.

plan-product

Version 0.12.9. Guided product planning in Markdown: define the product, seed and maintain Ubiquitous Language (docs/GLOSSARY.md), codify domain concepts and macro-flows, describe features, capture actor use cases, and sequence dependency-ordered development plans (docs/plans/development-plan.md) that hand off cleanly to dev-delivery.

Capabilities

The plugin operates as an Encapsulated Facade: the plan-product skill serves as the single conversational entrypoint, delegating to focused internal workflows, accompanied by six direct slash commands:

Command / WorkflowPurposeRunbook
plan-productDefine or refresh product purpose, Ubiquitous Language (docs/GLOSSARY.md), feature inventory, and high-level technology context.workflows/product.md
plan-conceptDefine an atomic domain concept or cross-feature macro-flow (C-nn, kind: domain-model | flow), reconciling Ubiquitous Language (docs/GLOSSARY.md).workflows/concept.md
plan-featureDefine one capability (F-gg.nn), its boundaries, inputs, outputs, acceptance checks, and dependencies.workflows/feature.md
plan-use-caseCapture an actor workflow (UC-gg.nn.uu), entry route, process tree, alternatives, failures, and acceptance checks.workflows/use-case.md
plan-developmentSequence product deliverables in docs/plans/development-plan.md with stable DP-pp.ss IDs, conditional CodeGraph Anchors: (docs/code-map/codegraph.db), observable - Verify: checkpoints, and dev-delivery handoff.workflows/development-plan.md
plan-maintainUpgrade legacy product planning documents from Model v1 or docs/roadmap.md to Model v2, or reconcile document integrity.workflows/maintain.md

The workflows interview for missing information, preserve existing content, use configured paths (user_home -> repo_root) and current templates, align with Ubiquitous Language (docs/GLOSSARY.md), and check for conflicting or duplicate ownership. Development plans describe delivery outcomes and architectural briefing notes; technical slice planning (docs/plans/dp-pp.ss-<slug>.md), adversarial plan review (plan-adversary), and clean-context code execution belong to dev-delivery (with automatic uc-*.md, feature.md, and docs/features.md completion roll-up as DP-pp.ss steps finish).

Canonical Numbering & Terminology Contract (v2)

Numbering PatternCanonical NameSegment DefinitionsPath / Location
C-nn(e.g. C-01)Concept ID• nn = Concept Number (01–99): Sequential atomic domain model or cross-feature macro-flow (kind: domain-model | flow).docs/concepts/c-nn-short-slug.md
F-gg.nn(e.g. F-01.02)Feature ID• gg = Feature Group (00–99): Cohesive functional area / domain clustering related features (00 = Foundation).• nn = Feature Number (01–99): Sequential feature within that Feature Group.docs/features/f-gg.nn/feature.md
UC-gg.nn.uu(e.g. UC-01.02.01)Use Case ID• gg = Feature Group (00–99): Inherited from parent Feature.• nn = Feature Number (01–99): Inherited from parent Feature.• uu = Use Case Number (01–99): Sequential actor workflow within F-gg.nn.docs/features/f-gg.nn/uc-gg.nn.uu-short-slug.md
DP-pp.ss(e.g. DP-01.03)Development Plan Step ID• pp = Phase (00–99 or 01–99): Technical delivery stage in build order.• ss = Step (01–99): Ordered unit of delivery work within Phase pp that completes/verifies target UC-gg.nn.uus (or F-gg.nn fallback).docs/plans/development-plan.md

Installation

The plugin is listed in the NyssaAI marketplace. Install plan-product from that marketplace in your host. The release is pinned there by tag and commit.

In Claude Code:

/plugin marketplace add NyssaAI/plugin-marketplace
/plugin install plan-product@nyssaai

Each host reads its projected harness-adapter: Claude Code uses .claude-plugin/plugin.json and commands/, Cursor uses .cursor-plugin/plugin.json, commands/, and skills/, Tessl uses .tessl-plugin/plugin.json and ./skills, Gemini uses gemini-extension.json and skills/, Antigravity stages .temp/dist/antigravity/ (with commands/ projected as plan-product-cmd-* skills), and Hermes Agent stages .temp/dist/hermes/ via harness-adapters/hermes/plugin.py.

Codex usage

Install the native plugin from the marketplace and invoke the facade skill:

  • plan-product:plan-product

Codex uses .codex-plugin/plugin.json and skills/. Direct command aliases are host-specific; use the installed skill entrypoint or specify desired workflows directly.

Project setup

From repo_root, run the initializer with Node.js 22 or later:

node <plugin_root>/src/init/init.mjs

Resolve plugin_root from PLAN_PRODUCT_PLUGIN_ROOT, PLUGIN_ROOT, CLAUDE_PLUGIN_ROOT, CURSOR_PLUGIN_ROOT, or the installed skill directory. Do not put installation-specific absolute paths in committed configuration. Configuration defaults resolve from user_home (~/.nyssa-ai/plan-product/config.json) and are overridden by repo_root (<repo_root>/.nyssa-ai/plan-product/config.json). runtime_root resolves via 4-step precedence (--runtime-root -> NYSSA_RUNTIME_ROOT -> <persona_cwd>/.nyssa-ai/plan-product/runtime/ when SOUL.md and IDENTITY.md exist -> configured runtimeRoot or .nyssa-ai/plan-product/runtime/). Usage telemetry is opt-in ("telemetry": { "enabled": false } default), creating zero usage/ directories or files unless telemetry.enabled === true (<runtime_root>/usage/events.jsonl).

The initializer creates missing configuration, schema, eight starter templates, and four core document starters (docs/product.md, docs/GLOSSARY.md, docs/features.md, docs/tech-stack.md). Re-running it fills missing configuration fields and restores missing templates at their configured locations while preserving existing user documents and custom templates.

<repo_root>/
|-- .nyssa-ai/plan-product/
|   |-- config.json
|   |-- schema.json
|   |-- runtime/usage/              Gitignored mutable usage telemetry (runtime_root).
|   `-- templates/
|       |-- product.md
|       |-- glossary.md
|       |-- features.md
|       |-- tech-stack.md
|       |-- concept.md
|       |-- feature.md
|       |-- use-case.md
|       `-- development-plan.md
`-- docs/
    |-- GLOSSARY.md                 Ubiquitous Language glossary (seeded by init, shared with dev-standards).
    |-- product.md
    |-- features.md
    |-- tech-stack.md
    |-- code-map/codegraph.db       Optional tracked CodeGraph snapshot read by plan-development.
    |-- specs/                      Optional JSON specifications for business entities (DTOs) & interfaces.
    |-- learnings/                  Optional grounded project lessons read into development-plan Gotchas.
    |-- plans/
    |   |-- development-plan.md     Created by plan-development (DP-pp.ss steps).
    |   `-- dp-01.01-example.md     Durable implementation plans authored by dev-delivery.
    |-- concepts/                   Created by plan-concept.
    |   `-- c-01-example.md
    `-- features/                   Created as features are defined.
        `-- f-01.01/
            |-- feature.md
            `-- uc-01.01.01-example.md  Created by plan-use-case.

All committed paths are relative to repo_root. .nyssa-ai/plan-product/config.json owns document locations, template locations, feature naming, and development plan naming. Customize those paths before planning. Existing documents remain in their current locations; changing a path does not move them automatically.

Development and evaluation

From a source checkout:

npm run validate
npm run assemble
npm test
npm run eval:prepare
npm pack --dry-run

Tests in test/unit/ and test/use_case/ exercise path containment, user_home -> repo_root precedence, runtime_root routing, fresh setup, custom paths and templates, preservation, model migrations, package contents, and the planning facade. The evaluation suite covers workflow routing and document-producing tasks across all six workflows.

License

Licensed under the Apache License 2.0. See CHANGELOG.md for release history.