sentrix plans
Generate, review, and manage implementation plans.
sentrix plans
Generate, review, and manage implementation plans. This command group covers plan creation, review, activation, and completion. AI implementation now lives under sentrix code generate.
Subcommands#
The plans subcommands fall into three categories:
- AI-powered —
generate,new, andreviewinvoke AI to produce or improve artifacts. - API sync and git operations —
complete,activate, andcancelupdate plan metadata, sync with the Sentrix API, and perform git operations. They do not invoke AI. - Local —
listreads local files only, with no API calls or AI invocations.
Note: Plan implementation has moved to
sentrix code generate.
sentrix plans generate#
Break a requirements document into multiple implementation plan files using AI.
Usage#
sentrix plans generate <target>
Arguments and Options#
| Argument/Flag | Type | Required | Default | Description |
|---|---|---|---|---|
target | path | Yes | Path to a directory containing 00-requirements.md, or a direct path to the requirements file. | |
--workflow | string | No | comprehensive | Workflow template name. Built-ins: basic, comprehensive. |
Creates numbered plan files (01-<name>.md, 02-<name>.md, etc.) in the same directory as the requirements file and syncs them to the Sentrix API.
Workflows#
The --workflow flag selects the AI prompt template used for plan generation. Two built-in workflows are available:
comprehensive (default) — A thorough, two-pass workflow designed to produce production-grade plans that require minimal review:
- Pass 1 (Read & Plan): Reads the requirements, architecture guides, and every source file referenced in the requirements before drafting anything.
- Pass 2 (Detail & Validate): Expands outlines into full implementation steps with copy-paste-ready code snippets, then self-validates against a strict checklist.
Comprehensive plans include required sections (Overview, Key Files table, Design Decisions, Implementation Steps, Checklist) and must satisfy 7 quality rules and 9 self-validation checks. Plans are split by architectural layer, target 2-4 hours of work each (~500 lines max), and are ordered by implementation sequence.
basic — A streamlined, single-pass workflow with 6 concise steps. Suitable for straightforward requirements where speed matters more than exhaustive detail. Plans include a ## Checklist section but have minimal structural requirements.
| Aspect | basic | comprehensive |
|---|---|---|
| Process | Single pass, 6 steps | Two-pass (Read & Plan, Detail & Validate) |
| Source file reading | Not explicitly required | Mandatory before writing code snippets |
| Code snippets | Expected | Must be copy-paste ready, complete functions |
| Quality checks | None explicit | 7 quality rules + 9 self-validation checks |
| Plan splitting guidance | Simple (independent, single concern) | By architectural layer, then entity; 2-4 hrs / ~500 lines |
| Plan document structure | Minimal (## Checklist required) | Full structure (Overview, Key Files, Design Decisions, Implementation Steps, Checklist) |
Examples#
sentrix plans generate plans/website/2026-02/feature-contact-form/
Use the comprehensive workflow for production-grade plans:
sentrix plans generate --workflow comprehensive plans/website/2026-02/feature-contact-form/
sentrix plans new#
Generate a single plan file without an existing requirements document using AI. Useful for standalone tasks.
Aliases: write, create
Usage#
sentrix plans new <plans_dir> --description <description> [--platform <platform>] [--draft]
Arguments and Options#
| Argument/Flag | Type | Required | Default | Description |
|---|---|---|---|---|
plans_dir | path | Yes | Directory where the plan should be created. | |
--description | string | Yes | Natural language description of what to implement. | |
--platform | string | No | from config | Platform override: any configured platform name from .sentrix/config.toml (for example nextjs, fastapi, ui-component, rust-cli, or a custom platform). |
--draft | bool | No | false | Mark the plan as draft status. |
sentrix plans new uses bundled internal prompts. It does not depend on repo-installed /sentrix-plan-new-* files under .claude/commands/, and Sentrix resolves the agent for this flow from command-specific configuration for the selected platform rather than a runtime-default provider.
Example#
sentrix plans new plans/website/2026-02/feature-contact-form/ \
--description "Add email validation to the contact form" \
--platform nextjs
sentrix plans review#
Review and improve an existing plan file using AI. The plan file is edited in-place with up to 5 review iterations.
Usage#
sentrix plans review <target> [--platform <platform>] [--workflow <name>] [--ask-questions]
Arguments and Options#
| Argument/Flag | Type | Required | Default | Description |
|---|---|---|---|---|
target | path | Yes | Path to a plan file or a plans directory. When a directory is given, all plan files in it are processed. | |
--platform | string | No | from config | Platform override to select the correct review command. |
--workflow | string | No | new single-plan reviews use iterative; unfinished requirements-directory resumes reuse the persisted workflow | Named review workflow. Brand-new requirements-directory reviews must pass requirements-iterative, requirements-adversarial, or multi-plan-comprehensive. |
--ask-questions | bool | No | false | Enable interactive question prompts (Step 0 and mid-review) for workflows that use them. multi-plan-comprehensive stays autonomous and does not use Step 0 or mid-review prompts. |
Review Workflows#
sentrix plans review supports these workflows:
iterative(default for new single-plan reviews; lead-only)iterative-per-agent(single-plan reviewer workflow)step-by-step-sequentialcombine-findingscross-plan-iterative(plans-directory targets only)requirements-iterative(requirements-aware directory workflow)requirements-adversarial(requirements-aware directory workflow)multi-plan-comprehensive(lead-only requirements-aware directory workflow)
If --workflow is omitted for a single numbered plan, sentrix plans review behaves the same as sentrix plans review --workflow iterative.
Unfinished requirements-directory resumes still use the persisted requirements workflow from requirements.review-state.json.
New requirements-directory reviews must pass --workflow requirements-iterative, --workflow requirements-adversarial, or --workflow multi-plan-comprehensive.
Completed requirements-directory reruns with --force must pass --workflow requirements-iterative --force, --workflow requirements-adversarial --force, or --workflow multi-plan-comprehensive --force.
cross-plan-iterative requires a plans directory target rather than a single plan file.
multi-plan-comprehensive is a lead-only requirements-aware directory workflow. It reviews the numbered plans against 00-requirements.md plus the configured architecture docs. Its prompt tells the lead agent to focus edits on numbered plan body content and avoid editing 00-requirements.md, plan frontmatter, or unrelated files, but that is prompt guidance rather than a CLI-enforced guarantee. It does not use Step 0 or mid-review prompts even when --ask-questions is passed.
Plans in plans/backlog/ cannot be reviewed — they must be activated first.
Example#
sentrix plans review plans/website/2026-02/feature-contact-form/01-feature-contact-form-component.md
Review all plans in a directory:
sentrix plans review plans/website/2026-02/feature-contact-form/
Lead-only requirements-aware directory review:
sentrix plans review plans/ai-ui/2026-03/feat-x/ --workflow multi-plan-comprehensive
sentrix plans complete#
Mark one or more plans as completed. Updates plan frontmatter with the completion timestamp, PR number, and commit SHAs.
Usage#
sentrix plans complete [<target>] [--pr <pr>] [--auto]
Arguments and Options#
| Argument/Flag | Type | Required | Default | Description |
|---|---|---|---|---|
target | path | No | Path to a plan file or a plans directory. Required when --auto is not used. | |
--pr | string | No | PR number to record. Required when --auto is not used. | |
--auto | bool | No | false | Automatically detect and complete plans from recent git history. |
Plans in plans/backlog/ cannot be completed — they must be activated first.
Dependencies: git is required. gh (GitHub CLI) is preferred for full-fidelity PR metadata; if you use it, authenticate with gh auth login for best results. When gh is unavailable or unusable (for example, not installed, not authenticated, or otherwise unusable), the CLI falls back to git-based PR lookup heuristics that reconstruct metadata from local merge commit history. The git-only fallback works only when local history preserves GitHub-style two-parent merge commits (Merge pull request #N); squash merges, rebase merges, and custom merge-message formats are not supported in git-only mode. The target PR must already be merged - non-merged PRs are rejected.
Auto-Complete Mode#
When --auto is used, <target> and --pr are not needed. Auto-complete runs in two passes:
- Pass 1: Completes in-progress plans that have a matching merged PR automatically without prompting.
- Pass 2: Scans for plans missing completion metadata and prompts interactively per plan ("Complete X with PR #Y? [y/n]").
Note: When
ghis unavailable or unusable, auto-complete uses git-based heuristics to discover merged PRs from local history. This works only for repositories with GitHub-style two-parent merge commits. If your repository uses squash merges, rebase merges, or custom merge-message formats, installing and authenticatingghis recommended for reliable auto-completion.
Confirmation Behavior#
- In single-file mode, prompts for re-confirmation when the plan is already marked completed.
- In directory mode, prompts only when all targeted plans are already completed.
- Use
--forceto skip the re-confirmation prompt.
Examples#
Complete a specific plan with a PR:
sentrix plans complete plans/website/2026-02/feature-contact-form/01-feature-contact-form-component.md --pr 42
Auto-complete all eligible plans:
sentrix plans complete --auto
Preview auto-complete without writing:
sentrix plans complete --auto --dry-run
sentrix plans activate#
Move requirements and plans from the backlog to the active plans directory.
Usage#
sentrix plans activate <target>
Arguments#
| Argument | Type | Required | Description |
|---|---|---|---|
target | path | Yes | Path to a directory containing 00-requirements.md, or a direct path to the requirements file. Must be in plans/backlog/. |
Moves files via git and syncs to the Sentrix API.
Example#
sentrix plans activate plans/backlog/website/feature-search/
sentrix plans list#
List plans with optional filtering. This is a local operation that does not call the API.
Usage#
sentrix plans list [--initiative <path>] [--status <status>...] [--app <app>] [--include-unsynced]
Options#
| Flag | Type | Default | Description |
|---|---|---|---|
--initiative | path | Filter by initiative file path. | |
--status | string | all | Filter by status. Repeatable (e.g., --status pending --status in_progress). |
--app | string | all | Filter by app name. |
--include-unsynced | bool | false | Include plans not yet synced to the API. |
Examples#
List all plans:
sentrix plans list
List pending and in-progress plans for the website:
sentrix plans list --app website --status pending --status in_progress
sentrix plans cancel#
Cancel one or more plans. Cancelled active plans are archived; cancelled backlog plans are permanently deleted.
Usage#
sentrix plans cancel <target>
Arguments#
| Argument | Type | Required | Description |
|---|---|---|---|
target | path | Yes | Path to a plan file, a plans directory, or a 00-requirements.md file for directory-level cancel. |
Behavior#
- Active plans: Syncs deletions to the API and moves files to
plans/archive/viagit mv. - Backlog plans: Permanently deletes files (no archive).
- Requirement cascade: When canceling at directory level (or when the last plan in a directory is canceled), the
00-requirements.mdis also affected — active requirements are archived, backlog requirements are permanently deleted. The empty source directory is removed.
The command prompts for confirmation per plan file before canceling. Use --force to skip confirmation prompts, or --dry-run (-n) to preview without writing.
Examples#
Cancel a specific plan:
sentrix plans cancel plans/website/2026-02/feature-contact-form/01-feature-contact-form-component.md
Cancel all plans in a directory:
sentrix plans cancel plans/website/2026-02/feature-contact-form/
Preview what would be canceled:
sentrix plans cancel plans/website/2026-02/feature-contact-form/ --dry-run