specdacular 0.6.1 → 0.6.3

package/README.md

@@ -8,11 +8,8 @@ Plan features specific enough that an agent can implement without asking questio
 npx specdacular
 ```
 
-> [!CAUTION]
-> **Early Discovery Phase.** This project is actively evolving as we explore workflow patterns for AI-assisted feature planning. Commands, file formats, and conventions change frequently between versions. We aim to provide backwards-compatible migrations, but breaking changes may occur. Pin to a specific version if stability matters to you.
-
-> [!WARNING]
-> **Open Source Software.** This is maintained by a small team in their free time. It installs slash commands and workflow files into your `.claude/` directory. Always use version control. Review what gets installed. Back up your work. The software is provided "as is" without warranty of any kind. By using this tool, you accept full responsibility for any changes it makes to your project.
+> [!NOTE]
+> **Early Discovery Phase.** Commands and conventions may change between versions. Pin to a specific version if stability matters to you.
 
 ---
 

package/commands/specd/config.md

@@ -0,0 +1,22 @@
+---
+name: specd:config
+description: Create or update .specd/config.json with commit settings
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Create or update `.specd/config.json` with global specd settings.
+
+Currently supports:
+- `auto_commit_docs` — Whether to auto-commit `.specd/` file changes (default: true)
+- `auto_commit_code` — Whether to auto-commit implementation code changes (default: true)
+</objective>
+
+<execution_context>
+@~/.claude/specdacular/workflows/config.md
+</execution_context>

package/commands/specd/help.md

@@ -47,6 +47,7 @@ Display available specdacular commands and usage guidance.
 
 | Command | Description |
 |---------|-------------|
+| `/specd:config` | Create or update `.specd/config.json` with commit settings |
 | `/specd:status [--all]` | Show feature status dashboard |
 | `/specd:blueprint [name] [sub]` | Generate visual blueprint (wireframes, diagrams) |
 | `/specd:update` | Update Specdacular to the latest version |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specdacular",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Feature planning system for existing codebases. Map, understand, and plan features in large projects.",
   "bin": {
     "specdacular": "bin/install.js"

package/specdacular/workflows/config.md

@@ -0,0 +1,112 @@
+<purpose>
+Create or update `.specd/config.json` with global specd settings.
+
+Supports:
+- `auto_commit_docs` — Whether to auto-commit `.specd/` file changes (default: true)
+- `auto_commit_code` — Whether to auto-commit implementation code changes (default: true)
+
+Preserves any existing fields in the config file (e.g., `type` for orchestrator mode).
+</purpose>
+
+<process>
+
+<step name="check_existing">
+Check if `.specd/config.json` already exists.
+
+```bash
+[ -f ".specd/config.json" ] && echo "exists" || echo "missing"
+```
+
+**If exists:**
+Read the file and parse current values.
+
+```
+Current `.specd/config.json`:
+
+- `auto_commit_docs`: {value or "not set"}
+- `auto_commit_code`: {value or "not set"}
+{any other fields shown as context}
+```
+
+**If missing:**
+```
+No `.specd/config.json` found. Will create one with commit settings.
+```
+
+Continue to ask_settings.
+</step>
+
+<step name="ask_settings">
+Ask user for preferred commit settings.
+
+Use AskUserQuestion:
+- header: "Commit Settings"
+- question: "Which auto-commit settings do you want?"
+- options:
+  - "Both on (default)" — `auto_commit_docs: true, auto_commit_code: true`
+  - "Docs only" — `auto_commit_docs: true, auto_commit_code: false`
+  - "Code only" — `auto_commit_docs: false, auto_commit_code: true`
+  - "Both off" — `auto_commit_docs: false, auto_commit_code: false`
+
+Map the selection to values:
+- "Both on (default)": `auto_commit_docs = true`, `auto_commit_code = true`
+- "Docs only": `auto_commit_docs = true`, `auto_commit_code = false`
+- "Code only": `auto_commit_docs = false`, `auto_commit_code = true`
+- "Both off": `auto_commit_docs = false`, `auto_commit_code = false`
+
+Continue to write_config.
+</step>
+
+<step name="write_config">
+Write the config file, preserving any existing fields.
+
+**If `.specd/config.json` exists:**
+Read the existing JSON. Merge `auto_commit_docs` and `auto_commit_code` into it, preserving all other fields.
+
+**If `.specd/config.json` does not exist:**
+Create `.specd/` directory if needed, then write new config with just the commit settings.
+
+**Ensure `.specd/` directory exists:**
+```bash
+mkdir -p .specd
+```
+
+**Write config:**
+Write `.specd/config.json` with the merged content. Example:
+```json
+{
+  "auto_commit_docs": true,
+  "auto_commit_code": true
+}
+```
+
+Continue to confirm.
+</step>
+
+<step name="confirm">
+Show the final config to the user.
+
+```
+Config written to `.specd/config.json`:
+
+{display full JSON content}
+
+**Settings:**
+- Auto-commit docs (.specd/ files): {on|off}
+- Auto-commit code (implementation): {on|off}
+
+These settings apply to all specd workflows in this project.
+To change later, run `/specd:config` again.
+```
+
+End workflow.
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] `.specd/config.json` exists with `auto_commit_docs` and `auto_commit_code` fields
+- [ ] Existing config fields preserved (not overwritten)
+- [ ] User confirmed settings via AskUserQuestion
+- [ ] Final config displayed to user
+</success_criteria>

package/specdacular/workflows/discuss-feature.md

@@ -312,6 +312,23 @@ Continue to commit.
 <step name="commit">
 Commit the discussion updates.
 
+**First, check auto-commit setting. Run this command:**
+
+```bash
+cat .specd/config.json 2>/dev/null || echo '{"auto_commit_docs": true}'
+```
+
+Read the output. If `auto_commit_docs` is `false`, do NOT run the git commands below. Instead print:
+
+```
+Auto-commit disabled for docs — changes not committed.
+Modified files: .specd/features/{feature-name}/CONTEXT.md, DECISIONS.md, STATE.md, config.json
+```
+
+Then skip ahead to completion.
+
+**Only if `auto_commit_docs` is `true` or not set (default), run:**
+
 ```bash
 git add .specd/features/{feature-name}/CONTEXT.md .specd/features/{feature-name}/DECISIONS.md .specd/features/{feature-name}/STATE.md .specd/features/{feature-name}/config.json
 git commit -m "docs({feature-name}): discussion session {N}

package/specdacular/workflows/execute-plan.md

@@ -81,7 +81,8 @@ Continue to load_context.
 Load ALL context needed for execution.
 
 **Read feature context:**
-- `config.json` — Feature settings (check `execution.auto_commit`)
+- `config.json` — Feature settings
+- `.specd/config.json` — Global settings (check `auto_commit_code` and `auto_commit_docs`)
 - `STATE.md` — Current progress, completed plans
 - `DECISIONS.md` — Constraints to follow during implementation
 - `RESEARCH.md` — Implementation notes, pitfalls (if exists)
@@ -180,7 +181,8 @@ Feature execution finished. Review:
 - Phase RESEARCH.md: patterns identified
 
 **Settings:**
-- Auto-commit: {yes | no} (from config.json)
+- Auto-commit code: {yes | no} (from .specd/config.json, default: yes)
+- Auto-commit docs: {yes | no} (from .specd/config.json, default: yes)
 
 **Next plan:** {plans/phase-XX/YY-PLAN.md}
 **Objective:** {one-line from plan}
@@ -328,23 +330,26 @@ Use AskUserQuestion:
 
 ### 5. Commit task (if auto_commit enabled)
 
-**Check config.json `execution.auto_commit`:**
+**First, check auto-commit setting. Run this command:**
 
-**If auto_commit is true:**
 ```bash
-git add {files from task}
-git commit -m "feat({feature}): {task description}"
+cat .specd/config.json 2>/dev/null || echo '{"auto_commit_code": true}'
 ```
 
-**If auto_commit is false:**
-- Do NOT commit
-- Show message:
+Read the output. If `auto_commit_code` is `false`, do NOT run the git commands below. Instead print:
+
 ```
-Task {N} complete. Changes ready for review.
-Files modified: {file list}
+Auto-commit disabled for code — changes not committed.
+Modified files: {files from task}
+```
+
+Then skip to step 6.
 
-Commit when ready:
-git add {files} && git commit -m "feat({feature}): {task description}"
+**Only if `auto_commit_code` is `true` or not set (default), run:**
+
+```bash
+git add {files from task}
+git commit -m "feat({feature}): {task description}"
 ```
 
 ### 6. Update STATE.md
@@ -381,18 +386,27 @@ Mark plan complete and suggest next.
 
 3. Update stage progress checkboxes
 
-**Commit STATE.md update (if auto_commit enabled):**
+**Commit STATE.md update. First, check auto-commit setting. Run this command:**
+
+```bash
+cat .specd/config.json 2>/dev/null || echo '{"auto_commit_docs": true}'
+```
+
+Read the output. If `auto_commit_docs` is `false`, do NOT run the git commands below. Instead print:
+
+```
+Auto-commit disabled for docs — STATE.md changes not committed.
+```
+
+Then skip ahead to "Find next plan".
+
+**Only if `auto_commit_docs` is `true` or not set (default), run:**
 
-**If auto_commit is true:**
 ```bash
 git add .specd/features/{feature}/STATE.md
 git commit -m "docs({feature}): complete plan {phase-XX/YY}"
 ```
 
-**If auto_commit is false:**
-- Do NOT commit
-- Include STATE.md in the list of modified files for user to review
-
 **Find next plan:**
 - Check ROADMAP.md for next plan in sequence
 - Or next phase if current phase complete

package/specdacular/workflows/map-codebase.md

@@ -356,7 +356,24 @@ Continue to commit_codebase_map.
 </step>
 
 <step name="commit_codebase_map">
-Commit the codebase map:
+Commit the codebase map.
+
+**First, check auto-commit setting. Run this command:**
+
+```bash
+cat .specd/config.json 2>/dev/null || echo '{"auto_commit_docs": true}'
+```
+
+Read the output. If `auto_commit_docs` is `false`, do NOT run the git commands below. Instead print:
+
+```
+Auto-commit disabled for docs — changes not committed.
+Modified files: .specd/codebase/*.md
+```
+
+Then skip ahead to completion.
+
+**Only if `auto_commit_docs` is `true` or not set (default), run:**
 
 ```bash
 git add .specd/codebase/*.md .specd/config.json

package/specdacular/workflows/new-feature.md

@@ -641,6 +641,23 @@ Continue to commit.
 <step name="commit">
 Commit the feature initialization.
 
+**First, check auto-commit setting. Run this command:**
+
+```bash
+cat .specd/config.json 2>/dev/null || echo '{"auto_commit_docs": true}'
+```
+
+Read the output. If `auto_commit_docs` is `false`, do NOT run the git commands below. Instead print:
+
+```
+Auto-commit disabled for docs — changes not committed.
+Modified files: .specd/features/{feature-name}/
+```
+
+Then skip ahead to completion.
+
+**Only if `auto_commit_docs` is `true` or not set (default), run:**
+
 ```bash
 git add .specd/features/{feature-name}/
 git commit -m "docs({feature-name}): initialize feature

package/specdacular/workflows/next-feature.md

@@ -592,6 +592,23 @@ Set `stage` to `"complete"`.
 **Update STATE.md:**
 Set stage to `complete`.
 
+**First, check auto-commit setting. Run this command:**
+
+```bash
+cat .specd/config.json 2>/dev/null || echo '{"auto_commit_docs": true}'
+```
+
+Read the output. If `auto_commit_docs` is `false`, do NOT run the git commands below. Instead print:
+
+```
+Auto-commit disabled for docs — feature completion not committed.
+Modified files: .specd/features/{name}/config.json, .specd/features/{name}/STATE.md
+```
+
+Then end the workflow.
+
+**Only if `auto_commit_docs` is `true` or not set (default), run:**
+
 ```bash
 git add .specd/features/{name}/config.json .specd/features/{name}/STATE.md
 git commit -m "docs({feature-name}): feature complete

package/specdacular/workflows/plan-feature.md

@@ -609,6 +609,23 @@ Continue to commit.
 <step name="commit">
 Commit the roadmap.
 
+**First, check auto-commit setting. Run this command:**
+
+```bash
+cat .specd/config.json 2>/dev/null || echo '{"auto_commit_docs": true}'
+```
+
+Read the output. If `auto_commit_docs` is `false`, do NOT run the git commands below. Instead print:
+
+```
+Auto-commit disabled for docs — changes not committed.
+Modified files: .specd/features/{feature-name}/ROADMAP.md, plans/, STATE.md, config.json
+```
+
+Then skip ahead to completion.
+
+**Only if `auto_commit_docs` is `true` or not set (default), run:**
+
 ```bash
 git add .specd/features/{feature-name}/ROADMAP.md .specd/features/{feature-name}/plans/ .specd/features/{feature-name}/STATE.md .specd/features/{feature-name}/config.json
 git commit -m "docs({feature-name}): create roadmap

package/specdacular/workflows/plan-phase.md

@@ -301,6 +301,23 @@ Continue to commit.
 <step name="commit">
 Commit the plans.
 
+**First, check auto-commit setting. Run this command:**
+
+```bash
+cat .specd/config.json 2>/dev/null || echo '{"auto_commit_docs": true}'
+```
+
+Read the output. If `auto_commit_docs` is `false`, do NOT run the git commands below. Instead print:
+
+```
+Auto-commit disabled for docs — changes not committed.
+Modified files: .specd/features/{feature-name}/plans/phase-{NN}/*-PLAN.md, ROADMAP.md, STATE.md
+```
+
+Then skip ahead to completion.
+
+**Only if `auto_commit_docs` is `true` or not set (default), run:**
+
 ```bash
 git add .specd/features/{feature-name}/plans/phase-{NN}/*-PLAN.md
 git add .specd/features/{feature-name}/ROADMAP.md

package/specdacular/workflows/prepare-phase.md

@@ -676,6 +676,23 @@ Continue to commit.
 <step name="commit">
 Commit the phase preparation.
 
+**First, check auto-commit setting. Run this command:**
+
+```bash
+cat .specd/config.json 2>/dev/null || echo '{"auto_commit_docs": true}'
+```
+
+Read the output. If `auto_commit_docs` is `false`, do NOT run the git commands below. Instead print:
+
+```
+Auto-commit disabled for docs — changes not committed.
+Modified files: .specd/features/{feature}/plans/phase-{NN}/CONTEXT.md, RESEARCH.md (if created), DECISIONS.md
+```
+
+Then skip ahead to completion.
+
+**Only if `auto_commit_docs` is `true` or not set (default), run:**
+
 ```bash
 # Add phase CONTEXT.md
 git add ".specd/features/{feature}/plans/phase-{NN}/CONTEXT.md"

package/specdacular/workflows/research-phase.md

@@ -515,6 +515,23 @@ Continue to commit.
 <step name="commit">
 Commit the phase research.
 
+**First, check auto-commit setting. Run this command:**
+
+```bash
+cat .specd/config.json 2>/dev/null || echo '{"auto_commit_docs": true}'
+```
+
+Read the output. If `auto_commit_docs` is `false`, do NOT run the git commands below. Instead print:
+
+```
+Auto-commit disabled for docs — changes not committed.
+Modified files: .specd/features/{feature}/plans/phase-{NN}/RESEARCH.md, DECISIONS.md
+```
+
+Then skip ahead to completion.
+
+**Only if `auto_commit_docs` is `true` or not set (default), run:**
+
 ```bash
 git add ".specd/features/{feature}/plans/phase-{NN}/RESEARCH.md"
 git add ".specd/features/{feature}/DECISIONS.md"

package/specdacular/workflows/review-phase.md

@@ -450,7 +450,23 @@ Continue to commit_and_next.
 <step name="commit_and_next">
 Commit review changes and suggest next steps.
 
-**Commit changes:**
+**First, check auto-commit setting. Run this command:**
+
+```bash
+cat .specd/config.json 2>/dev/null || echo '{"auto_commit_docs": true}'
+```
+
+Read the output. If `auto_commit_docs` is `false`, do NOT run the git commands below. Instead print:
+
+```
+Auto-commit disabled for docs — changes not committed.
+Modified files: .specd/features/{feature}/STATE.md, DECISIONS.md, CHANGELOG.md, config.json, plans/phase-{NN}/
+```
+
+Then skip ahead to presenting next steps below.
+
+**Only if `auto_commit_docs` is `true` or not set (default), run:**
+
 ```bash
 git add .specd/features/{feature}/STATE.md
 git add .specd/features/{feature}/DECISIONS.md

package/specdacular/workflows/status.md

@@ -10,17 +10,39 @@
 
 Check if `$ARGUMENTS` contains `--all`. If so, completed features will be shown in a separate section.
 
-### 2. Check for features directory
+### 2. Detect orchestrator mode
+
+Read `.specd/config.json` if it exists.
+
+```bash
+cat .specd/config.json 2>/dev/null
+```
+
+**If config exists and `type` equals `"orchestrator"`:**
+- Set mode = orchestrator
+- Read `projects` array from config.json — each entry has `name` and `path`
+- Continue to step 3
+
+**Otherwise (no config, or type != "orchestrator"):**
+- Set mode = project
+- Continue to step 3
+
+### 3. Check for features directory
 
 Use Glob to check if `.specd/features/*/config.json` matches anything.
 
-If no matches: output the following and stop:
+**If mode = orchestrator and no root features:**
+Also check sub-project features — scan each project path for `{project-path}/.specd/features/*/config.json`. If features found in sub-projects, continue (there's something to show).
+
+**If no features found anywhere:** output the following and stop:
 
 ```
 No features found. Start one with `/specd:feature:new [name]`.
 ```
 
-### 3. Gather feature data
+### 4. Gather feature data
+
+#### If mode = project (single-project, unchanged):
 
 For each feature directory in `.specd/features/`:
 
@@ -30,7 +52,32 @@ For each feature directory in `.specd/features/`:
    - **Plan completion**: From the `Plan Status` table, count rows with Status = `Complete` vs total rows. Format as `completed/total` (e.g. `5/8`). If no Plan Status table or no rows, use `—`.
    - **Next action**: Extract the first meaningful line from the `## Next Steps` section. Keep it short — take just the **Recommended:** line if present, otherwise the first line. Strip markdown formatting like `**Recommended:**` prefix. Truncate to ~50 chars if needed.
 
-### 4. Sort features
+#### If mode = orchestrator:
+
+**Step 4a: Gather root features (same as single-project).**
+
+For each feature directory in `.specd/features/`, extract feature_name, created, stage, plans, next_action using the same logic as single-project mode.
+
+**Step 4b: For each root feature, check for sub-project features.**
+
+Read each root feature's `config.json`. If it has a `projects` array (orchestrator feature):
+
+For each project entry `{name, path}` in the feature's `projects` array:
+1. Check if `{path}/.specd/features/{feature_name}/` exists
+2. If yes, read `{path}/.specd/features/{feature_name}/config.json` and `{path}/.specd/features/{feature_name}/STATE.md`
+3. Extract the same fields: stage (from STATE.md `**Stage:**`), plan completion, next action
+4. Store as a sub-feature of the parent orchestrator feature, tagged with the project name
+
+Mark this root feature as an "orchestrator feature" (has sub-project children).
+
+**Step 4c: Scan for standalone sub-project features.**
+
+For each project in the repo-level `.specd/config.json` `projects` array:
+1. Use Glob to find `{project-path}/.specd/features/*/config.json`
+2. For each feature found, check if it was already captured as a sub-feature of an orchestrator feature in step 4b
+3. If NOT already captured, gather its data (same extraction logic) and store as a standalone feature, grouped by project name/path
+
+### 5. Sort features
 
 Sort active features by stage priority (highest first), then by created date (oldest first):
 
@@ -39,7 +86,14 @@ Sort active features by stage priority (highest first), then by created date (ol
 3. `research`
 4. `discussion` (least advanced)
 
-### 5. Format output
+**For orchestrator mode:** Apply the same sort to:
+- Root/orchestrator features (the parent rows)
+- Sub-project features within each orchestrator feature
+- Standalone features within each project group
+
+### 6. Format output
+
+#### If mode = project (single-project, unchanged):
 
 **Count features:** Calculate total count and in-progress count (non-complete).
 
@@ -80,6 +134,78 @@ Run `/specd:status --all` to include completed features.
 
 Where `Completed` date comes from the `**Last Updated:**` field in STATE.md.
 
-### 6. Output
+#### If mode = orchestrator:
+
+**Count features:** Calculate total across root features + standalone sub-project features. In-progress = non-complete/non-abandoned.
+
+**Output header:**
+
+```
+# Feature Status
+
+_{total} features, {in_progress} in progress — orchestrator mode_
+```
+
+**Active features table (orchestrator features with sub-projects):**
+
+For each active root feature (not complete/abandoned, unless `--all`):
+
+If it's an orchestrator feature (has sub-project children):
+
+```
+| Feature | Stage | Plans | Created | Next Action |
+|---------|-------|-------|---------|-------------|
+| {name} | {stage} | {plans} | {created} | {next_action} |
+|  └ {project-name} | {stage} | {plans} | | {next_action} |
+|  └ {project-name} | {stage} | {plans} | | {next_action} |
+```
+
+- Orchestrator feature is the parent row with full data
+- Sub-project rows use `└ {project-name}` in the Feature column
+- Sub-project rows leave Created empty (inherited from parent)
+- Sort sub-project rows by stage priority (same as main sort)
+
+If it's a plain root feature (no sub-project children), show it as a normal row (same as single-project).
+
+**If standalone sub-project features exist, add a section:**
+
+```
+### Project Features
+```
+
+For each project that has standalone features:
+
+```
+**{project-name}** ({project-path})
+
+| Feature | Stage | Plans | Created | Next Action |
+|---------|-------|-------|---------|-------------|
+| {name} | {stage} | {plans} | {created} | {next_action} |
+```
+
+Only show active standalone features (not complete/abandoned, unless `--all`).
+
+**Completed/abandoned features with `--all` flag:**
+
+**If `--all` flag is NOT set and there are completed/abandoned features (root or sub-project):**
+
+```
+Run `/specd:status --all` to include completed features.
+```
+
+**If `--all` flag IS set and there are completed/abandoned features, add:**
+
+```
+### Completed
+
+| Feature | Plans | Completed |
+|---------|-------|-----------|
+| {name} | {completed}/{total} | {last_updated} |
+|  └ {project-name} | {completed}/{total} | {last_updated} |
+```
+
+Show completed orchestrator features with their sub-project rows indented, and completed standalone sub-project features under their project heading.
+
+### 7. Output
 
 Print the formatted dashboard directly. No file writes. No Task agents. No AskUserQuestion.