[Spec] Configuration System for Defaults (No-Prompt Execution)

# Configuration System for Defaults (No-Prompt Execution)

## Overview

Add a repository-level configuration system (`.superpowers-config.json`) that stores default preferences, eliminating repetitive prompts for workflow decisions that should only be asked once per repository.

**Core principle:** One-time configuration + subagent-based reading = consistent defaults without context pollution.

**Store specs as issues. No local file storage.**

## Problem Statement

Currently, two skills prompt the user on every invocation:

1. **writing-plans** - Asks which execution method to use (subagent vs inline) after writing each plan
2. **using-git-worktrees** - Asks where to create worktrees (project-local vs global) when setting up worktrees

These are repository-level preferences that should be configured once, not prompted repeatedly. Additionally, a third setting (`workflowMode`) is needed for future git workflow configuration.

## Goals

1. **Eliminate repetitive prompts** - Ask once, save preference, never ask again for that repository
2. **Scale without context pollution** - As config grows, skills only receive values they need, not full config
3. **Team consistency** - Configuration is version controlled, shared across team
4. **Extensibility** - Design allows future settings to be added easily

## Architecture

### Components

1. **`.superpowers-config.json`** - Repository-level configuration file (version controlled, committed to repo)
2. **`skills/shared/config-reader.md`** - Shared module that skills invoke via subagent
3. **Skill integration** - Skills dispatch config-reader subagents to read config, receiving minimal context

### Flow

```
Skill needs config value
  ↓
Dispatch subagent with config-reader module
  ↓
Subagent checks for .superpowers-config.json
  ↓
If missing: Prompt user → create file → return value
If exists: Read file → extract requested values → return value
  ↓
Skill continues with minimal context (just the values it needs)
```

## Configuration Schema

```json
{
  "defaultExecutionMethod": "subagent" | "inline",
  "defaultWorktreeLocation": "project-local" | "global",
  "workflowMode": "placeholder"
}
```

### Field Definitions

**`defaultExecutionMethod`** (required)
- Values: `"subagent"` | `"inline"`
- Controls: writing-plans execution handoff section
- Behavior: 
  - `"subagent"` - Use subagent-driven-development skill (no prompt)
  - `"inline"` - Use executing-plans skill (no prompt)
- Default (if missing): `"subagent"`

**`defaultWorktreeLocation`** (required)
- Values: `"project-local"` | `"global"`
- Controls: using-git-worktrees directory selection section
- Behavior:
  - `"project-local"` - Use `.worktrees/` directory (verify it's gitignored)
  - `"global"` - Use `~/.config/superpowers/worktrees/<project-name>/`
- Default (if missing): `"project-local"`

**`workflowMode`** (required, placeholder)
- Values: Currently `"placeholder"` only
- Purpose: Reserved for future git workflow settings (develop/main branching, deployment targets, review requirements, etc.)
- Note: "Will be implemented in future session" - no user prompt for this field

### Schema Validation Rules

1. All three fields must be present
2. `defaultExecutionMethod` must be `"subagent"` or `"inline"`
3. `defaultWorktreeLocation` must be `"project-local"` or `"global"`
4. `workflowMode` must be `"placeholder"` (future: additional enum values)
5. Invalid values → Error message, skill stops execution

## Config-Reader Module

**Location:** `skills/shared/config-reader.md`

### Purpose

Subagent module that handles all configuration operations. Skills dispatch this module via the Task tool with `subagent_type: "general"`, receiving minimal structured data in return.

### Responsibilities

1. Check if `.superpowers-config.json` exists
2. If missing: Run first-run prompt sequence (one question at a time)
3. If exists: Read and validate file
4. Extract only requested values (apply defaults for missing optional fields)
5. Return minimal context to calling skill

### Interface

**Calling skill dispatches:**

```
[Task tool invocation]
subagent_type: "general"
description: "Read config for execution method"
prompt: "Use skills/shared/config-reader to get config values: defaultExecutionMethod, defaultWorktreeLocation"
```

**Config-reader subagent returns:**

```json
{
  "defaultExecutionMethod": "subagent",
  "defaultWorktreeLocation": "project-local"
}
```

**Critical:** Subagent returns only the requested values, not the full config file, not file paths, not extra context.

### Module Structure

**File:** `skills/shared/config-reader.md`

**Sections:**

1. **Purpose & Interface** - What it does, how skills invoke it
2. **Config Schema** - Full JSON schema with field descriptions
3. **First-Run Sequence** - Prompt flow when config is missing
4. **Read Operations** - How to extract and return requested values
5. **Validation** - Schema validation, applying defaults
6. **Error Handling** - Malformed config, missing fields, invalid values

### Module Design Principle

- Invoked via Task tool with `subagent_type: "general"`
- Returns structured data (JSON object), not prose
- Never returns the full config file contents
- Only returns what the calling skill explicitly requested
- Single responsibility: configuration reading and first-run setup

## First-Run Prompt Sequence

**When:** `.superpowers-config.json` doesn't exist

**Trigger:** Any skill needing config dispatches config-reader subagent

**Sequence:**

```
1. Subagent checks for .superpowers-config.json
   ↓ Not found
   
2. Subagent prompts: 
   "Superpowers needs to configure default settings for this repository.
   
   Which execution method should be used for plan implementation?
   
   1. Subagent-driven (recommended) - Fresh subagent per task with two-stage review
   2. Inline execution - Execute tasks in current session
   
   Which approach?"
   ↓ User selects
   
3. Subagent prompts:
   "Where should git worktrees be created by default?
   
   1. .worktrees/ (project-local, hidden, version controlled gitignore)
   2. ~/.config/superpowers/worktrees/<project-name>/ (global, outside project)
   
   Which location?"
   ↓ User selects
   
4. Subagent creates .superpowers-config.json with:
   {
     "defaultExecutionMethod": "<user-choice>",
     "defaultWorktreeLocation": "<user-choice>",
     "workflowMode": "placeholder"
   }
   
5. Subagent creates git commit:
   git add .superpowers-config.json
   git commit -m "Add superpowers config with default settings"
   
6. Subagent returns the requested values to calling skill
```

**One commit:** Config file is created with all three initial values in a single commit.

**Note:** `workflowMode` does NOT get a prompt - saved as `"placeholder"` automatically, no user interaction for this field.

## Skill Integration

### writing-plans Integration

**Current behavior (lines 180-186):**
- After creating plan issue, offer execution choice with two options
- Wait for user response
- Proceed to chosen skill

**New behavior:**

```
After creating the plan issue:

1. Use Task tool to dispatch config-reader subagent
   Prompt: "Use skills/shared/config-reader to get config value: defaultExecutionMethod"

2. Config-reader subagent:
   - Checks for .superpowers-config.json
   - If missing: Runs first-run sequence, returns user's choice
   - If exists: Reads file, validates, returns value
   
3. Receive response: { "defaultExecutionMethod": "subagent" } or { "defaultExecutionMethod": "inline" }

4. Proceed without prompting:
   - If "subagent": Invoke subagent-driven-development skill
   - If "inline": Invoke executing-plans skill

5. Continue with chosen execution approach
```

**Removed:** The "Which approach?" question and user prompt.

### using-git-worktrees Integration

**Current behavior (lines 20-48):**
- Check for existing worktree directories (.worktrees or worktrees)
- Check CLAUDE.md for preference
- If no existing directory and no CLAUDE.md preference, ask user
- Proceed with chosen location

**New behavior:**

```
Before worktree creation:

1. Use Task tool to dispatch config-reader subagent
   Prompt: "Use skills/shared/config-reader to get config value: defaultWorktreeLocation"

2. Config-reader subagent:
   - Checks for .superpowers-config.json
   - If missing: Runs first-run sequence, returns user's choice
   - If exists: Reads file, validates, returns value
   
3. Receive response: { "defaultWorktreeLocation": "project-local" } or { "defaultWorktreeLocation": "global" }

4. Proceed without prompting:
   - If "project-local": Use .worktrees/ (verify it's gitignored)
   - If "global": Use ~/.config/superpowers/worktrees/<project-name>/

5. Continue with worktree creation
```

**Removed:** The directory priority check for CLAUDE.md and the "Where should I create worktrees?" question.

**Kept:** Safety verification - for project-local, still verify `.worktrees/` is ignored in `.gitignore`.

### Other Skills

Future skills that need configuration will use the same pattern:
1. Dispatch config-reader subagent via Task tool
2. Specify which values they need
3. Receive minimal context
4. Proceed without prompting

## Error Handling & Edge Cases

### Scenario 1: Malformed JSON

**Situation:** Config file exists but has syntax errors (JSON.parse fails)

**Response:**
```
Configuration file has syntax errors. 
File: .superpowers-config.json
Error: [line number, unexpected token, etc.]

Fix the invalid JSON and try again.
```

**Behavior:** Calling skill stops execution. User must manually fix the config file.

### Scenario 2: Missing Required Field

**Situation:** Config exists but missing `defaultExecutionMethod`

**Response:** Config-reader applies schema default (`"subagent"`), includes warning in returned data:

```json
{
  "defaultExecutionMethod": "subagent",
  "warning": "Config missing field [defaultExecutionMethod], using default: subagent"
}
```

**Behavior:** Calling skill continues with default value. Warning logged but doesn't block execution.

### Scenario 3: Invalid Enum Value

**Situation:** `defaultExecutionMethod` is `"parallel"` (not valid option)

**Response:**
```
Invalid configuration value.
Field: defaultExecutionMethod
Value: "parallel"
Valid values: "subagent" or "inline"

Fix the configuration and try again.
```

**Behavior:** Calling skill stops execution. User must manually fix the config file.

### Scenario 4: Config File Not in Git

**Situation:** First-run creates `.superpowers-config.json`, git shows it as untracked

**Behavior:** 
- Config-reader commits the file during first-run setup
- If user removes it from git after commit, that's their choice
- Git operations remain separate concern - config-reader doesn't force-add later

### Scenario 5: First-Run Interrupted

**Situation:** User starts first-run prompt, answers question 1, then ends session before completing

**Behavior:**
- Config file doesn't exist (wasn't created)
- Next session: Config-reader detects missing config
- Restarts first-run sequence from beginning (not resume from where stopped)
- Answers from previous session are not saved

**Rationale:** Simpler implementation. Resumable first-run would require partial state tracking.

## File Changes

### New Files to Create

**`skills/shared/config-reader.md`**
- Purpose: Subagent module for configuration reading and first-run setup
- Sections: Purpose, Schema, First-Run, Read Ops, Validation, Error Handling

### Files to Modify

**`skills/writing-plans/SKILL.md`**
- Lines 180-186 (Execution Handoff section): Replace prompt-based choice with config-reader subagent dispatch
- Add integration note: "Uses superpowers:config-reader for execution method default"

**`skills/using-git-worktrees/SKILL.md`**
- Lines 20-48 (Directory Selection Process section): Replace priority check + prompt with config-reader subagent dispatch
- Remove CLAUDE.md check (superceded by config file)
- Keep safety verification (gitignore check for project-local)
- Add integration note: "Uses superpowers:config-reader for worktree location default"

## Testing Strategy

### Unit Testing

**Config-reader module tests:**
1. First-run sequence creates valid config file
2. First-run prompts appear in correct order (one at a time)
3. Config file is committed to git
4. Missing config triggers first-run, not error
5. Valid config returns requested values
6. Missing field uses default value
7. Invalid enum value returns error
8. Malformed JSON returns error with details

### Integration Testing

**writing-plans integration:**
1. Config exists with "subagent" → Invokes subagent-driven-development without prompt
2. Config exists with "inline" → Invokes executing-plans without prompt
3. Config missing → First-run prompts appear, then correct skill invoked
4. Malformed config → Skill stops with error, doesn't proceed

**using-git-worktrees integration:**
1. Config exists with "project-local" → Uses .worktrees/ without prompt
2. Config exists with "global" → Uses global directory without prompt
3. Config missing → First-run prompts appear, then correct location used
4. project-local still verifies .gitignore

### End-to-End Scenarios

**Scenario A: Fresh repository, first run**
- User invokes writing-plans or using-git-worktrees
- Config missing → First-run sequence starts
- User answers prompts
- Config file created and committed
- Skill proceeds with chosen defaults
- Later calls use config, no prompts

**Scenario B: Existing repository with config**
- User invokes writing-plans or using-git-worktrees
- Config exists → Config-reader reads and validates
- Values returned to calling skill
- Skill proceeds without prompts
- Fast execution, no repeated questions

**Scenario C: Team member clones repo with existing config**
- Config is committed to repo
- Team member pulls → config already exists
- No first-run prompts for them
- They use team's shared defaults

## Security Considerations

### Config File Content

**Risks:** Config file could contain:
- Unexpected fields from manual editing
- Malicious JSON (excessive nesting, large strings)

**Mitigations:**
- Config-reader validates schema strictly
- Rejects unknown fields
- Limits nesting depth (2 levels max)
- Limits file size (1KB max)

### Path Injection

**Risks:** `defaultWorktreeLocation` could contain path traversal (`../`)

**Mitigations:**
- Config-reader validates enum values
- Only "project-local" and "global" allowed
- Paths are constructed by skill, not from config

### Subagent Trust

**Risks:** Config-reader subagent could return unexpected data

**Mitigations:**
- Calling skill validates response structure
- Missing required keys → Error
- Unexpected keys → Ignored

## Migration Path

### Existing Repositories

**Migration is automatic:** On first invocation of writing-plans or using-git-worktrees after upgrade:
- Config missing → First-run sequence triggers
- User sets preferences once
- Config file created
- Future invocations use config

**No manual migration required.** CLAUDE.md preferences are no longer checked (superseded by config file).

### Breaking Changes

**Removed behaviors:**
1. writing-plans no longer prompts for execution method
2. using-git-worktrees no longer checks CLAUDE.md for preferences
3. using-git-worktrees no longer prompts for worktree location

**If users relied on CLAUDE.md:** They must create `.superpowers-config.json` manually or let first-run create it.

**If users want different behavior:** They must edit `.superpowers-config.json` directly.

## Future Extensions

### Adding New Settings

**Process:**
1. Add field to config schema with default value
2. Update config-reader validation
3. Update skills that need the new setting
4. Document in schema section

**Example: Adding `preferredModel` for subagent dispatch**

```json
{
  "defaultExecutionMethod": "subagent",
  "defaultWorktreeLocation": "project-local",
  "workflowMode": "placeholder",
  "preferredModel": "auto"
}
```

- Config-reader reads, validates, returns to requesting skill
- Skill uses value for subagent model selection
- No first-run prompt (field has default)
- Users can manually edit if needed

### Workflow Mode Implementation

When `workflowMode` is implemented in future session:
1. Add enum values to schema: `"placeholder"` | `"gitflow"` | `"trunk"` | etc.
2. Replace `"placeholder"` default with `"gitflow"` (or appropriate default)
3. Add prompt to first-run sequence (between executionMethod and worktreeLocation)
4. Update relevant skills to use workflowMode value
5. Document workflow behaviors in schema

### Team Overrides

**Future consideration:** Allow `.superpowers-config.local.json` for developer-specific overrides (not committed to repo)

- Would be gitignored
- Merged with base config
- Useful for individual preference (e.g., preferred editor)

**Not in initial implementation.** Can be added later if needed.

## Success Criteria

1. **No repetitive prompts** - writing-plans and using-git-worktrees never prompt for preferences more than once per repository
2. **Fast execution** - Config lookup via subagent is fast, doesn't block skill execution
3. **Team consistency** - Committed config file ensures all team members use same defaults
4. **Extensibility** - New settings can be added without touching core skill logic
5. **Clean separation** - Config-reader module handles all config operations, skills stay focused
6. **Error resilience** - Invalid configs produce clear errors, don't crash skills
7. **First-run UX** - Clear prompts, one question at a time, automatic commit

[Spec] Configuration System for Defaults (No-Prompt Execution) #5

Description

Configuration System for Defaults (No-Prompt Execution)

Overview

Problem Statement

Goals

Architecture

Components

Flow

Configuration Schema

Field Definitions

Schema Validation Rules

Config-Reader Module

Purpose

Responsibilities

Interface

Module Structure

Module Design Principle

First-Run Prompt Sequence

Skill Integration

writing-plans Integration

using-git-worktrees Integration

Other Skills

Error Handling & Edge Cases

Scenario 1: Malformed JSON

Scenario 2: Missing Required Field

Scenario 3: Invalid Enum Value

Scenario 4: Config File Not in Git

Scenario 5: First-Run Interrupted

File Changes

New Files to Create

Files to Modify

Testing Strategy

Unit Testing

Integration Testing

End-to-End Scenarios

Security Considerations

Config File Content

Path Injection

Subagent Trust

Migration Path

Existing Repositories

Breaking Changes

Future Extensions

Adding New Settings

Workflow Mode Implementation

Team Overrides

Success Criteria

Metadata

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Issue actions