Configuration¶

Project settings live in .planning/config.json. Set during /new-project or edit interactively with /settings.

Full schema¶

{
  "mode": "interactive",
  "granularity": "standard",
  "model_profile": "balanced",
  "learning_mode": "auto",
  "context": "dev",
  "test_first": false,
  "planning": {
    "commit_docs": true,
    "commit_mode": "auto",
    "search_gitignored": false
  },
  "workflow": {
    "research": true,
    "plan_check": true,
    "verifier": true,
    "validation": true,
    "review": true,
    "solutions_search": true,
    "security_enforcement": true,
    "discuss_mode": "discuss",
    "tdd_mode": false
  },
  "parallelization": {
    "enabled": false,
    "plan_level": true,
    "task_level": false,
    "max_concurrent_agents": 5,
    "min_plans_for_parallel": 2
  },
  "gates": {
    "confirm_project": true,
    "confirm_phases": true,
    "confirm_roadmap": true,
    "confirm_plan": true,
    "execute_next_plan": true,
    "issues_review": true,
    "confirm_transition": true
  },
  "safety": {
    "always_confirm_destructive": true,
    "always_confirm_external_services": true
  },
  "review": {
    "auto_after_verify": false
  },
  "ship": {
    "auto_test": true,
    "conventional_commits": true,
    "pr_template": true
  },
  "hooks": {
    "context_warnings": true
  },
  "git": {
    "branching_strategy": "none",
    "phase_branch_template": "phase-{phase}-{slug}",
    "milestone_branch_template": "{milestone}-{slug}"
  }
}

Core settings¶

mode¶

Controls how much the agent auto-approves vs. asks for confirmation.

granularity¶

Controls the size of phases in the roadmap.

model_profile¶

Sets the tier of AI model used per agent role.

large = Claude Opus 4.6 / Gemini 3.1 Pro / GPT-5.4
medium = Claude Sonnet 4.6 / Gemini 3.1 Flash / GPT-5.4-mini
small = Claude Haiku 4.5 / Gemini 3.1 Flash-Lite / GPT-5.4-nano
Windsurf, Cursor, and OpenCode use the platform default — tiers signal intended task complexity.

Switch quickly: /set-profile quality · /set-profile balanced · /set-profile budget

learning_mode¶

parallelization¶

context (v2.2)¶

Controls the agent's output style by loading a context profile from learnship/contexts/.

Switch with /settings or edit config.json directly. Takes effect on the next workflow run.

test_first (v2.0)¶

Planning settings¶

planning.commit_docs¶

planning.commit_mode¶

planning.search_gitignored¶

Workflow toggles¶

workflow.discuss_mode (v2.3.4)¶

Controls the depth of questioning in /discuss-phase and /new-project Step 3.

Equivalent to passing --deep flag: discuss-phase N --deep or new-project --deep.

When to use "deep": Complex phases with many implementation choices, new domains, or when past phases revealed too many ambiguous decisions.

Review settings (v2.0)¶

Ship settings (v2.0)¶

Git branching¶

"git": {
  "branching_strategy": "phase",
  "phase_branch_template": "phase-{phase}-{slug}"
}

Template variables: {phase} = phase number, {slug} = kebab-case phase name, {milestone} = milestone version.

Speed vs. quality presets¶

Apply a preset with /settings or edit config.json directly. The /set-profile command switches model_profile only: for full preset changes use /settings.

Editing settings¶

Interactive editor:

/settings

One-step model switch:

/set-profile quality
/set-profile balanced
/set-profile budget

Direct edit: Open .planning/config.json in your editor: changes take effect immediately on the next workflow run.

Session hooks (v2.2)¶

On Claude Code and Gemini CLI, learnship installs 4 session hooks via settings.json:

Hooks are installed automatically during npx learnship --claude or --gemini. Other platforms (Windsurf, OpenCode, Codex, Cursor) do not support hooks and are unaffected.

Interactive questions (v2.2)¶

14 workflows now use structured interactive questions for user-facing decisions. Instead of plain numbered text lists, the agent presents choices using your platform's native question tool:

install.js automatically rewrites the tool name for each platform — you don't need to configure anything.

Upgrade safety (v2.2)¶

After every install, learnship generates learnship-file-manifest.json with SHA-256 hashes of all installed files. On the next upgrade:

1. The installer compares current files against the manifest
2. Files you modified locally are detected automatically
3. Modified files are backed up to learnship-local-patches/ before overwriting
4. After upgrade, run /reapply-patches to restore your customizations