diff --git a/CHANGELOG.md b/CHANGELOG.md index 382c592..0d23a8a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,58 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [1.22.2] - 2026-03-30 + +Overview: Major upstream sync from GSD v1.30.0 adding autonomous execution, fast mode, UI design pipeline, multi-project workspaces, user profiling, forensics, and 25 new slash commands. Full documentation now available in four additional locales (ja-JP, ko-KR, pt-BR, zh-CN). Added `mode: subagent` declarations to all agent definition files. + +### Added + +- `/gsd-autonomous` command and `autonomous` workflow for end-to-end autonomous project execution +- `/gsd-fast` command and `fast` workflow for rapid-fire task execution +- `/gsd-do` command and `do` workflow for direct task execution without full planning +- `/gsd-forensics` command and `forensics` workflow for post-mortem investigation and debugging +- `/gsd-thread` command for threaded conversation management +- `/gsd-workstreams` command and `workstream.cjs` library for multi-stream work management with `--workstream` flag +- `/gsd-profile-user` command, `profile-user` workflow, `gsd-user-profiler` agent, `profile-pipeline.cjs`, and `profile-output.cjs` for building and maintaining user preference profiles +- `/gsd-ui-phase` command, `ui-phase` workflow, `gsd-ui-researcher` agent, `gsd-ui-auditor` agent, `gsd-ui-checker` agent for complete UI design and review pipeline +- `/gsd-ui-review` command and `ui-review` workflow for retroactive UI audits +- `/gsd-ship` command and `ship` workflow for streamlined shipping and release +- `/gsd-pr-branch` command and `pr-branch` workflow for PR branch creation and management +- `/gsd-manager` command and `manager` workflow for manager-level project oversight +- `/gsd-session-report` command and `session-report` workflow for session summary generation +- `/gsd-stats` command and `stats` workflow for project and milestone statistics +- `/gsd-note` command and `note` workflow for quick note-taking during work +- `/gsd-add-backlog` and `/gsd-review-backlog` commands for backlog item management +- `/gsd-milestone-summary` command and `milestone-summary` workflow for milestone overview generation +- `/gsd-new-workspace`, `/gsd-list-workspaces`, and `/gsd-remove-workspace` commands and workflows for multi-project workspace management +- `/gsd-next` command and `next` workflow for determining and starting the next task +- `/gsd-plant-seed` command and `plant-seed` workflow for seeding new project ideas +- `/gsd-audit-uat` command, `audit-uat` workflow, and `uat.cjs` library for user acceptance testing audits +- `/gsd-review` command and `review` workflow for structured code review +- `gsd-advisor-researcher` agent for researching gray area decisions with comparison tables +- `gsd-assumptions-analyzer` agent and `discuss-phase-assumptions` workflow for assumption analysis during discuss phase +- `model-profiles.cjs` library for model profile definitions +- `security.cjs` library for security utility functions +- `node-repair` workflow for automated Node.js dependency repair +- `UI-SPEC.md`, `claude-md.md`, `dev-preferences.md`, `discussion-log.md`, and `user-profile.md` templates +- `user-profiling.md` and `workstream-flag.md` reference documentation +- `superpowers/plans/2026-03-18-materialize-new-project-config.md` and `superpowers/specs/2026-03-20-multi-project-workspaces-design.md` design documents +- Skill definitions (SKILL.md) for gsd-audit-milestone, gsd-cleanup, gsd-complete-milestone, gsd-discuss-phase, gsd-execute-phase, gsd-plan-phase, gsd-ui-phase, gsd-ui-review, and gsd-verify-work +- `mode: subagent` declarations added to all 18 agent definition files in `gsd-opencode/agents/` +- Full Japanese (ja-JP) documentation: AGENTS, ARCHITECTURE, CLI-TOOLS, COMMANDS, CONFIGURATION, FEATURES, README, USER-GUIDE, context-monitor, and workflow-discuss-mode +- Full Korean (ko-KR) documentation: AGENTS, ARCHITECTURE, CLI-TOOLS, COMMANDS, CONFIGURATION, FEATURES, README, USER-GUIDE, context-monitor, and workflow-discuss-mode +- Brazilian Portuguese (pt-BR) documentation: AGENTS, ARCHITECTURE, CLI-TOOLS, COMMANDS, CONFIGURATION, FEATURES, README, USER-GUIDE, context-monitor, and workflow-discuss-mode +- Simplified Chinese (zh-CN) documentation: README, USER-GUIDE, and full references subdirectory (checkpoints, continuation-format, decimal-phase-calculation, git-integration, git-planning-commit, model-profile-resolution, model-profiles, phase-argument-parsing, planning-config, questioning, tdd, ui-brand, verification-patterns) + +### Changed + +- Updated 12 existing agents (codebase-mapper, debugger, executor, integration-checker, nyquist-auditor, phase-researcher, plan-checker, planner, project-researcher, research-synthesizer, roadmapper, verifier) with improved behavior +- Enhanced 8 existing commands (discuss-phase, execute-phase, plan-phase, research-phase, debug, quick, reapply-patches, set-profile) +- Improved 30 existing workflows including execute-phase, plan-phase, discuss-phase, new-project, new-milestone, health, help, settings, and update +- Updated 12 CLI library modules (commands, config, core, frontmatter, init, milestone, phase, roadmap, state, template, verify, gsd-tools) for v1.30.0 compatibility +- Modified templates: config.json, context.md, phase-prompt.md, project.md, and UAT.md +- Updated 7 reference documents: checkpoints, decimal-phase-calculation, git-integration, model-profile-resolution, model-profiles, phase-argument-parsing, and planning-config + ## [1.22.0] - 2026-03-08 Overview: Synchronized with upstream GSD v1.22.4 to fix agent execution syntax and prevent unexpected stops. Simplified model profile system from quality/balanced/budget to simple/smart/genius with updated configuration file structure. Enhanced copy and translate services for upstream synchronization. diff --git a/README.md b/README.md index 08f497b..1a1f0e4 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@
-# GET SHIT DONE for OpenCode. (Based on TÂCHES v1.22.4 - 2026-03-03) +# GET SHIT DONE for OpenCode. (Based on TÂCHES v1.30.0 - 2026-03-30) **A light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES. (Adapted for OpenCode by rokicool and enthusiasts)** @@ -87,6 +87,12 @@ I just love both GSD and OpenCode. I felt like having GSD available only for Cla — **Roman** +## Version 1.30.0 + +We are keeping up with original GSDv1 v1.30.0 (2026-03-30) + +There is a controvertial solution I used to support "skill(skill='command-name')" syntax. Apart from that everything is expected to be fully functional. + ## Version 1.22.1 I decided to add 'mode: subagent' property to all custom agents. It should not affect any GSD functionality. However, it should remove unnecessary agents out of the list, available by Tab. diff --git a/assets/bin/gsd-translate-in-place.js b/assets/bin/gsd-translate-in-place.js index 64e2be5..60a5739 100644 --- a/assets/bin/gsd-translate-in-place.js +++ b/assets/bin/gsd-translate-in-place.js @@ -19,8 +19,8 @@ * 2 Runtime error (file I/O, permissions) */ -import { readFile, writeFile, access } from 'node:fs/promises'; -import { resolve, dirname } from 'node:path'; +import { readFile, writeFile, access, mkdir } from 'node:fs/promises'; +import { resolve, dirname, basename } from 'node:path'; import { fileURLToPath } from 'node:url'; // Use dynamic import for tinyglobby @@ -269,6 +269,159 @@ async function loadConfig(configPath) { return loadConfigs([configPath]); } +async function ensureCommandNames(apply) { + const commandsDir = resolve(__dirname, '../../gsd-opencode/commands/gsd'); + + let commandFiles; + try { + commandFiles = await glob(['*.md'], { cwd: commandsDir, onlyFiles: true, absolute: true }); + } catch { + console.log('No command files found to check for missing name: field.'); + return { fixed: 0, missing: 0 }; + } + + if (!commandFiles || commandFiles.length === 0) { + console.log('No command files found to check for missing name: field.'); + return { fixed: 0, missing: 0 }; + } + + let fixed = 0; + let missing = 0; + + for (const filePath of commandFiles) { + const commandName = basename(filePath, '.md'); + let content; + + try { + content = await readFile(filePath, 'utf-8'); + } catch { + continue; + } + + const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/); + if (!frontmatterMatch) continue; + + const frontmatter = frontmatterMatch[1]; + + if (/^name:/m.test(frontmatter)) continue; + + missing++; + const newFrontmatter = `name: ${commandName}\n${frontmatter}`; + const newContent = content.replace( + /^---\n([\s\S]*?)\n---/, + `---\n${newFrontmatter}\n---` + ); + + if (apply) { + await writeFile(filePath, newContent, 'utf-8'); + console.log(` Fixed missing name: in ${commandName}.md`); + fixed++; + } else { + console.log(` [dry-run] Would add name: ${commandName} to ${commandName}.md`); + } + } + + if (missing > 0) { + console.log(`Command name check: ${missing} file(s) missing name: field${apply ? `, ${fixed} fixed` : ' (dry-run)'}`); + } else { + console.log('All command files have name: in frontmatter.'); + } + + return { fixed, missing }; +} + +async function discoverGsdSkillReferences(searchPatterns) { + const files = await glob(searchPatterns, { + ignore: ['node_modules/**', '.git/**'], + onlyFiles: true + }); + + if (!files || files.length === 0) { + return new Set(); + } + + const skillRefs = new Set(); + const pattern = /skill\(skill="gsd-([^"]+)"/g; + + for (const file of files) { + try { + const content = await readFile(file, 'utf-8'); + let match; + while ((match = pattern.exec(content)) !== null) { + skillRefs.add(`gsd-${match[1]}`); + } + pattern.lastIndex = 0; + } catch { + // skip unreadable files + } + } + + return skillRefs; +} + +async function generateSkillWrappers(commandNames) { + const commandsDir = resolve(__dirname, '../../gsd-opencode/commands/gsd'); + const skillsBaseDir = resolve(__dirname, '../../gsd-opencode/skills'); + + const commandSet = new Set(commandNames); + let created = 0; + let skipped = 0; + let notFound = 0; + + for (const commandName of commandSet) { + const commandFile = resolve(commandsDir, `${commandName}.md`); + const skillDir = resolve(skillsBaseDir, commandName); + const skillFile = resolve(skillDir, 'SKILL.md'); + + try { + await access(commandFile); + } catch { + console.warn(` Command file not found: ${commandName}.md`); + notFound++; + continue; + } + + try { + await access(skillFile); + skipped++; + continue; + } catch { + // file doesn't exist yet, proceed + } + + const content = await readFile(commandFile, 'utf-8'); + + const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/); + let skillContent; + + if (frontmatterMatch) { + const originalFm = frontmatterMatch[1].trim(); + const body = frontmatterMatch[2]; + + const nameMatch = originalFm.match(/^name:\s*(.+)$/m); + const commandDisplayName = nameMatch ? nameMatch[1].trim() : commandName; + + const newFrontmatter = [ + `---`, + `name: ${commandName}`, + `description: Implementation of ${commandDisplayName} command`, + `---` + ].join('\n'); + + skillContent = newFrontmatter + '\n\n' + body; + } else { + skillContent = `---\nname: ${commandName}\ndescription: Implementation of ${commandName} command\n---\n\n` + content; + } + + await mkdir(skillDir, { recursive: true }); + await writeFile(skillFile, skillContent, 'utf-8'); + created++; + } + + console.log(`Skill wrappers: created ${created}, skipped ${skipped} (already exist), not found ${notFound}`); + return { created, skipped, notFound }; +} + /** * Main execution */ @@ -483,6 +636,19 @@ async function main() { } console.log(''); + + console.log('Checking command files for missing name: in frontmatter...'); + await ensureCommandNames(args.apply); + console.log(''); + + const skillRefs = await discoverGsdSkillReferences(config.patterns); + if (skillRefs.size > 0) { + console.log(`Discovered ${skillRefs.size} gsd skill reference(s): ${[...skillRefs].join(', ')}`); + await generateSkillWrappers([...skillRefs]); + } else { + console.log('No gsd skill references found in processed files.'); + } + console.log(formatter.formatSuccess('Done!')); process.exit(EXIT_SUCCESS); } diff --git a/assets/configs/config.json b/assets/configs/config.json index e2c537b..6d49716 100644 --- a/assets/configs/config.json +++ b/assets/configs/config.json @@ -264,13 +264,21 @@ "description": "Generic regex to convert any remaining tools list to YAML map" }, { - "_comment": "Generic regex fallback for any remaining tools: lines", + "_comment": "allowed-tools with inline tool list (e.g. 'allowed-tools: Read, Write, Edit')", + "pattern": "^allowed-tools: ([A-Za-z, ]+)$", + "replacement": "permissions", + "caseSensitive": true, + "isRegex": true, + "transform": "allowed_tools_inline_to_yaml", + "description": "Convert inline allowed-tools list to YAML permissions map" + }, + { + "_comment": "allowed-tools without inline list (multiline, already handled by - Read rules)", "pattern": "allowed-tools:", "replacement": "permissions:", "caseSensitive": true, "isRegex": false, - "transform": "allowed-tools to permissions", - "description": "" + "description": "Rename allowed-tools key to permissions for multiline format" }, { "pattern": "", @@ -320,6 +328,12 @@ "caseSensitive": true, "description": "Transform named color purple to hex" }, + { + "pattern": "color: magenta", + "replacement": "color: \"#FF00FF\"", + "caseSensitive": true, + "description": "Transform named color purple to hex" + }, { "pattern": "All arguments become", "replacement": "$ARGUMENTS become", @@ -332,6 +346,16 @@ "caseSensitive": true, "description": "Transform general-purpose subagent type to general" }, + { + "pattern": "'general-purpose'", + "replacement": "'general'", + "description": "Fix: quoted general-purpose subagent type name to general" + }, + { + "pattern": "general-purpose research agent", + "replacement": "general research agent", + "description": "Fix: general-purpose research agent description in discuss-phase-assumptions" + }, { "pattern": "subagent_type=\"Explore\"", "replacement": "subagent_type=\"explore\"", @@ -344,6 +368,16 @@ "caseSensitive": true, "description": "Transform task subagent type to general" }, + { + "pattern": "skill(skill=\"gsd:", + "replacement": "skill(skill=\"gsd-", + "description": "Fix: v1.30.0 introduced skill() calls with gsd: prefix instead of gsd- prefix" + }, + { + "pattern": "`gsd:discuss-phase`", + "replacement": "`gsd-discuss-phase`", + "description": "Fix: standalone gsd:discuss-phase reference in autonomous.md note" + }, { "pattern": "CLAUDE.md", "replacement": "AGENTS.md", @@ -399,6 +433,31 @@ "replacement": "get-shit-done/workflows/oc-set-profile.md", "description": "Use OpenCode related process instead of Claude Code's one" }, + { + "pattern": "!`node \"$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs\" config-set-model-profile $ARGUMENTS --raw`", + "replacement": "\n Switch the model profile used by GSD agents. Controls which OpenCode model each agent uses, balancing quality vs token spend.\n\n Routes to the set-profile workflow which handles:\n - Argument validation (simple/smart/genius)\n - Config file creation if missing\n - Profile update in config.json\n - Confirmation with model table display\n \n\n \n @$HOME/.config/opencode/get-shit-done/workflows/oc-set-profile.md\n \n\n \n **Follow the set-profile workflow** from `@$HOME/.config/opencode/get-shit-done/workflows/oc-set-profile.md`.\n\n The workflow handles all logic including:\n 1. Profile argument validation\n 2. Config file ensuring\n 3. Config reading and updating\n 4. Model table generation from MODEL_PROFILES\n 5. Confirmation display\n ", + "description": "Use OpenCode related process instead of Claude Code's one" + }, + { + "pattern": "", + "replacement": "", + "description": "gsd-reapply-patches.md" + }, + { + "pattern": "", + "replacement": "", + "description": "gsd-reapply-patches.md" + }, + { + "pattern": "Manage parallel workstreams for concurrent milestone work.", + "replacement": "\nManage parallel workstreams for concurrent milestone work.\n", + "description": "gsd-reapply-patches.md" + }, + { + "pattern": "Show the following output to the user verbatim, with no extra commentary:", + "replacement": "", + "description": "gsd-set-profile" + }, { "pattern": "default: `balanced`", "replacement": "default: `simple`", @@ -495,6 +554,7 @@ "name: set-profile", "subagent_type=\"general-purpose\"", "subagent_type=\"Explore\"", - "CLAUDE.md" + "CLAUDE.md", + "config-set-model-profile" ] } diff --git a/assets/configs/opus-made-config.json b/assets/configs/opus-made-config.json index ec45b10..edfce2c 100644 --- a/assets/configs/opus-made-config.json +++ b/assets/configs/opus-made-config.json @@ -12,9 +12,7 @@ "**/*.yml", "**/*.toml" ], - "include": [ - "gsd-opencode/**" - ], + "include": ["gsd-opencode/**"], "exclude": [ "node_modules/**", ".git/**", @@ -633,6 +631,12 @@ "caseSensitive": true, "description": "Transform named color purple to hex" }, + { + "pattern": "color: magenta", + "replacement": "color: \"#FF00FF\"", + "caseSensitive": true, + "description": "Transform named color purple to hex" + }, { "pattern": "All arguments become", "replacement": "$ARGUMENTS become", diff --git a/assets/configs/v1.28.0.json b/assets/configs/v1.28.0.json new file mode 100644 index 0000000..223ab9f --- /dev/null +++ b/assets/configs/v1.28.0.json @@ -0,0 +1,33 @@ +{ + "_description": "Supplemental translation rules for v1.28.0 -- fixes remaining forbidden strings after base translation", + "include": ["gsd-opencode/**"], + "exclude": [ + "node_modules/**", + ".git/**", + ".translate-backups/**", + "**/oc-*", + "**/*-oc-*" + ], + "rules": [ + { + "pattern": "rokicool/get-shit-done", + "replacement": "anomalyco/opencode", + "description": "Fix: GitHub badge/star-history references use wrong repo path" + }, + { + "pattern": "skill(skill=\"gsd:", + "replacement": "skill(skill=\"gsd-", + "description": "Fix: skill() function calls use colon instead of dash" + }, + { + "pattern": "`gsd:", + "replacement": "`gsd-", + "description": "Fix: Code references in backticks use colon instead of dash" + }, + { + "pattern": "general-purpose", + "replacement": "generic", + "description": "Fix: Remove forbidden general-purpose term (use 'generic' instead)" + } + ] +} diff --git a/assets/configs/v1.29.0.json b/assets/configs/v1.29.0.json new file mode 100644 index 0000000..8351e50 --- /dev/null +++ b/assets/configs/v1.29.0.json @@ -0,0 +1,23 @@ +{ + "_description": "Supplemental translation rules for v1.29.0 -- fixes remaining forbidden strings (general-purpose, gsd: command syntax)", + "include": ["gsd-opencode/**"], + "exclude": [ + "node_modules/**", + ".git/**", + ".translate-backups/**", + "**/oc-*", + "**/*-oc-*" + ], + "rules": [ + { + "pattern": "general-purpose", + "replacement": "general", + "description": "Fix: 'general-purpose' subagent type is forbidden in OpenCode" + }, + { + "pattern": "gsd:", + "replacement": "gsd-", + "description": "Fix: gsd: command syntax (Claude Code) to gsd- (OpenCode)" + } + ] +} diff --git a/assets/lib/translator.js b/assets/lib/translator.js index d600067..772d2f6 100644 --- a/assets/lib/translator.js +++ b/assets/lib/translator.js @@ -273,6 +273,19 @@ export class TextTranslator { return 'tools:\n' + tools.map(t => ` ${t}: true`).join('\n'); } + if (rule.transform === 'allowed_tools_inline_to_yaml') { + const toolsList = captureGroups[0]; + const tools = toolsList.split(',').map(t => t.trim()).filter(t => t); + const toolNameMap = { + 'Read': 'read', 'Write': 'write', 'Edit': 'edit', 'Bash': 'bash', + 'Glob': 'glob', 'Grep': 'grep', 'WebSearch': 'websearch', + 'WebFetch': 'webfetch', 'Task': 'task', 'TodoWrite': 'todowrite', + 'AskUserQuestion': 'question', 'Question': 'question' + }; + const mapped = tools.map(t => toolNameMap[t] || t.toLowerCase()); + return 'permissions:\n' + mapped.map(t => ` ${t}: true`).join('\n'); + } + // Substitute backreferences ($1, $2, etc.) with captured groups let replacement = processedReplacement; for (let i = 0; i < captureGroups.length; i++) { diff --git a/assets/prompts/M-COPY-AND-TRANSLATE.md b/assets/prompts/M-COPY-AND-TRANSLATE.md index 7f04ab5..4ec09a9 100644 --- a/assets/prompts/M-COPY-AND-TRANSLATE.md +++ b/assets/prompts/M-COPY-AND-TRANSLATE.md @@ -34,6 +34,7 @@ Before starting, verify these conditions. If any fail, fix them before proceedin ```bash # 1. Submodule must be initialized and up to date git submodule update --init --recursive +cd original/get-shit-done && git fetch --tags && git checkout $(git tag --sort=-creatordate | head -1) # 2. Dependencies must be installed npm install --prefix assets diff --git a/gsd-opencode/agents/gsd-advisor-researcher.md b/gsd-opencode/agents/gsd-advisor-researcher.md new file mode 100644 index 0000000..bd42c63 --- /dev/null +++ b/gsd-opencode/agents/gsd-advisor-researcher.md @@ -0,0 +1,112 @@ +--- +name: gsd-advisor-researcher +description: Researches a single gray area decision and returns a structured comparison table with rationale. Spawned by discuss-phase advisor mode. +mode: subagent +tools: + read: true + bash: true + grep: true + glob: true + websearch: true + webfetch: true + mcp__context7__*: true +color: "#00FFFF" +--- + + +You are a GSD advisor researcher. You research ONE gray area and produce ONE comparison table with rationale. + +Spawned by `discuss-phase` via `task()`. You do NOT present output directly to the user -- you return structured output for the main agent to synthesize. + +**Core responsibilities:** +- Research the single assigned gray area using OpenCode's knowledge, Context7, and web search +- Produce a structured 5-column comparison table with genuinely viable options +- write a rationale paragraph grounding the recommendation in the project context +- Return structured markdown output for the main agent to synthesize + + + +Agent receives via prompt: + +- `` -- area name and description +- `` -- phase description from roadmap +- `` -- brief project info +- `` -- one of: `full_maturity`, `standard`, `minimal_decisive` + + + +The calibration tier controls output shape. Follow the tier instructions exactly. + +### full_maturity +- **Options:** 3-5 options +- **Maturity signals:** Include star counts, project age, ecosystem size where relevant +- **Recommendations:** Conditional ("Rec if X", "Rec if Y"), weighted toward battle-tested tools +- **Rationale:** Full paragraph with maturity signals and project context + +### standard +- **Options:** 2-4 options +- **Recommendations:** Conditional ("Rec if X", "Rec if Y") +- **Rationale:** Standard paragraph grounding recommendation in project context + +### minimal_decisive +- **Options:** 2 options maximum +- **Recommendations:** Decisive single recommendation +- **Rationale:** Brief (1-2 sentences) + + + +Return EXACTLY this structure: + +``` +## {area_name} + +| Option | Pros | Cons | Complexity | Recommendation | +|--------|------|------|------------|----------------| +| {option} | {pros} | {cons} | {surface + risk} | {conditional rec} | + +**Rationale:** {paragraph grounding recommendation in project context} +``` + +**Column definitions:** +- **Option:** Name of the approach or tool +- **Pros:** Key advantages (comma-separated within cell) +- **Cons:** Key disadvantages (comma-separated within cell) +- **Complexity:** Impact surface + risk (e.g., "3 files, new dep -- Risk: memory, scroll state"). NEVER time estimates. +- **Recommendation:** Conditional recommendation (e.g., "Rec if mobile-first", "Rec if SEO matters"). NEVER single-winner ranking. + + + +1. **Complexity = impact surface + risk** (e.g., "3 files, new dep -- Risk: memory, scroll state"). NEVER time estimates. +2. **Recommendation = conditional** ("Rec if mobile-first", "Rec if SEO matters"). Not single-winner ranking. +3. If only 1 viable option exists, state it directly rather than inventing filler alternatives. +4. Use OpenCode's knowledge + Context7 + web search to verify current best practices. +5. Focus on genuinely viable options -- no padding. +6. Do NOT include extended analysis -- table + rationale only. + + + + +## Tool Priority + +| Priority | Tool | Use For | Trust Level | +|----------|------|---------|-------------| +| 1st | Context7 | Library APIs, features, configuration, versions | HIGH | +| 2nd | webfetch | Official docs/READMEs not in Context7, changelogs | HIGH-MEDIUM | +| 3rd | websearch | Ecosystem discovery, community patterns, pitfalls | Needs verification | + +**Context7 flow:** +1. `mcp__context7__resolve-library-id` with libraryName +2. `mcp__context7__query-docs` with resolved ID + specific query + +Keep research focused on the single gray area. Do not explore tangential topics. + + + +- Do NOT research beyond the single assigned gray area +- Do NOT present output directly to user (main agent synthesizes) +- Do NOT add columns beyond the 5-column format (Option, Pros, Cons, Complexity, Recommendation) +- Do NOT use time estimates in the Complexity column +- Do NOT rank options or declare a single winner (use conditional recommendations) +- Do NOT invent filler options to pad the table -- only genuinely viable approaches +- Do NOT produce extended analysis paragraphs beyond the single rationale paragraph + diff --git a/gsd-opencode/agents/gsd-assumptions-analyzer.md b/gsd-opencode/agents/gsd-assumptions-analyzer.md new file mode 100644 index 0000000..8385fc9 --- /dev/null +++ b/gsd-opencode/agents/gsd-assumptions-analyzer.md @@ -0,0 +1,110 @@ +--- +name: gsd-assumptions-analyzer +description: Deeply analyzes codebase for a phase and returns structured assumptions with evidence. Spawned by discuss-phase assumptions mode. +mode: subagent +tools: + read: true + bash: true + grep: true + glob: true +color: "#00FFFF" +--- + + +You are a GSD assumptions analyzer. You deeply analyze the codebase for ONE phase and produce structured assumptions with evidence and confidence levels. + +Spawned by `discuss-phase-assumptions` via `task()`. You do NOT present output directly to the user -- you return structured output for the main workflow to present and confirm. + +**Core responsibilities:** +- read the ROADMAP.md phase description and any prior CONTEXT.md files +- Search the codebase for files related to the phase (components, patterns, similar features) +- read 5-15 most relevant source files +- Produce structured assumptions citing file paths as evidence +- Flag topics where codebase analysis alone is insufficient (needs external research) + + + +Agent receives via prompt: + +- `` -- phase number and name +- `` -- phase description from ROADMAP.md +- `` -- summary of locked decisions from earlier phases +- `` -- scout results (relevant files, components, patterns found) +- `` -- one of: `full_maturity`, `standard`, `minimal_decisive` + + + +The calibration tier controls output shape. Follow the tier instructions exactly. + +### full_maturity +- **Areas:** 3-5 assumption areas +- **Alternatives:** 2-3 per Likely/Unclear item +- **Evidence depth:** Detailed file path citations with line-level specifics + +### standard +- **Areas:** 3-4 assumption areas +- **Alternatives:** 2 per Likely/Unclear item +- **Evidence depth:** File path citations + +### minimal_decisive +- **Areas:** 2-3 assumption areas +- **Alternatives:** Single decisive recommendation per item +- **Evidence depth:** Key file paths only + + + +1. read ROADMAP.md and extract the phase description +2. read any prior CONTEXT.md files from earlier phases (find via `find .planning/phases -name "*-CONTEXT.md"`) +3. Use glob and grep to find files related to the phase goal terms +4. read 5-15 most relevant source files to understand existing patterns +5. Form assumptions based on what the codebase reveals +6. Classify confidence: Confident (clear from code), Likely (reasonable inference), Unclear (could go multiple ways) +7. Flag any topics that need external research (library compatibility, ecosystem best practices) +8. Return structured output in the exact format below + + + +Return EXACTLY this structure: + +``` +## Assumptions + +### [Area Name] (e.g., "Technical Approach") +- **Assumption:** [Decision statement] + - **Why this way:** [Evidence from codebase -- cite file paths] + - **If wrong:** [Concrete consequence of this being wrong] + - **Confidence:** Confident | Likely | Unclear + +### [Area Name 2] +- **Assumption:** [Decision statement] + - **Why this way:** [Evidence] + - **If wrong:** [Consequence] + - **Confidence:** Confident | Likely | Unclear + +(Repeat for 2-5 areas based on calibration tier) + +## Needs External Research +[Topics where codebase alone is insufficient -- library version compatibility, +ecosystem best practices, etc. Leave empty if codebase provides enough evidence.] +``` + + + +1. Every assumption MUST cite at least one file path as evidence. +2. Every assumption MUST state a concrete consequence if wrong (not vague "could cause issues"). +3. Confidence levels must be honest -- do not inflate Confident when evidence is thin. +4. Minimize Unclear items by reading more files before giving up. +5. Do NOT suggest scope expansion -- stay within the phase boundary. +6. Do NOT include implementation details (that's for the planner). +7. Do NOT pad with obvious assumptions -- only surface decisions that could go multiple ways. +8. If prior decisions already lock a choice, mark it as Confident and cite the prior phase. + + + +- Do NOT present output directly to user (main workflow handles presentation) +- Do NOT research beyond what the codebase contains (flag gaps in "Needs External Research") +- Do NOT use web search or external tools (you have read, bash, grep, glob only) +- Do NOT include time estimates or complexity assessments +- Do NOT generate more areas than the calibration tier specifies +- Do NOT invent assumptions about code you haven't read -- read first, then form opinions + diff --git a/gsd-opencode/agents/gsd-codebase-mapper.md b/gsd-opencode/agents/gsd-codebase-mapper.md index 913cad5..f745b29 100644 --- a/gsd-opencode/agents/gsd-codebase-mapper.md +++ b/gsd-opencode/agents/gsd-codebase-mapper.md @@ -9,8 +9,6 @@ tools: glob: true write: true color: "#00FFFF" -skills: - - gsd-mapper-workflow # hooks: # PostToolUse: # - matcher: "write|edit" diff --git a/gsd-opencode/agents/gsd-debugger.md b/gsd-opencode/agents/gsd-debugger.md index 8bcd77b..8397a4e 100644 --- a/gsd-opencode/agents/gsd-debugger.md +++ b/gsd-opencode/agents/gsd-debugger.md @@ -10,9 +10,8 @@ tools: grep: true glob: true websearch: true +permissionMode: acceptEdits color: "#FFA500" -skills: - - gsd-debugger-workflow # hooks: # PostToolUse: # - matcher: "write|edit" @@ -419,6 +418,39 @@ git bisect bad # or good, based on testing 100 commits between working and broken: ~7 tests to find exact breaking commit. +## Follow the Indirection + +**When:** Code constructs paths, URLs, keys, or references from variables — and the constructed value might not point where you expect. + +**The trap:** You read code that builds a path like `path.join(configDir, 'hooks')` and assume it's correct because it looks reasonable. But you never verified that the constructed path matches where another part of the system actually writes/reads. + +**How:** +1. Find the code that **produces** the value (writer/installer/creator) +2. Find the code that **consumes** the value (reader/checker/validator) +3. Trace the actual resolved value in both — do they agree? +4. Check every variable in the path construction — where does each come from? What's its actual value at runtime? + +**Common indirection bugs:** +- Path A writes to `dir/sub/hooks/` but Path B checks `dir/hooks/` (directory mismatch) +- Config value comes from cache/template that wasn't updated +- Variable is derived differently in two places (e.g., one adds a subdirectory, the other doesn't) +- Template placeholder (`{{VERSION}}`) not substituted in all code paths + +**Example:** Stale hook warning persists after update +``` +Check code says: hooksDir = path.join(configDir, 'hooks') + configDir = $HOME/.config/opencode + → checks $HOME/.config/opencode/hooks/ + +Installer says: hooksDest = path.join(targetDir, 'hooks') + targetDir = $HOME/.config/opencode/get-shit-done + → writes to $HOME/.config/opencode/get-shit-done/hooks/ + +MISMATCH: Checker looks in wrong directory → hooks "not found" → reported as stale +``` + +**The discipline:** Never assume a constructed path is correct. Resolve it to its actual value and verify the other side agrees. When two systems share a resource (file, directory, key), trace the full path in both. + ## Technique Selection | Situation | Technique | @@ -429,6 +461,7 @@ git bisect bad # or good, based on testing | Know the desired output | Working backwards | | Used to work, now doesn't | Differential debugging, Git bisect | | Many possible causes | Comment out everything, Binary search | +| Paths, URLs, keys constructed from variables | Follow the indirection | | Always | Observability first (before making changes) | ## Combining Techniques @@ -743,6 +776,48 @@ Can I observe the behavior directly? + + +## Purpose + +The knowledge base is a persistent, append-only record of resolved debug sessions. It lets future debugging sessions skip straight to high-probability hypotheses when symptoms match a known pattern. + +## File Location + +``` +.planning/debug/knowledge-base.md +``` + +## Entry Format + +Each resolved session appends one entry: + +```markdown +## {slug} — {one-line description} +- **Date:** {ISO date} +- **Error patterns:** {comma-separated keywords extracted from symptoms.errors and symptoms.actual} +- **Root cause:** {from Resolution.root_cause} +- **Fix:** {from Resolution.fix} +- **Files changed:** {from Resolution.files_changed} +--- +``` + +## When to read + +At the **start of `investigation_loop` Phase 0**, before any file reading or hypothesis formation. + +## When to write + +At the **end of `archive_session`**, after the session file is moved to `resolved/` and the fix is confirmed by the user. + +## Matching Logic + +Matching is keyword overlap, not semantic similarity. Extract nouns and error substrings from `Symptoms.errors` and `Symptoms.actual`. Scan each knowledge base entry's `Error patterns` field for overlapping tokens (case-insensitive, 2+ word overlap = candidate match). + +**Important:** A match is a **hypothesis candidate**, not a confirmed diagnosis. Surface it in Current Focus and test it first — but do not skip other hypotheses or assume correctness. + + + ## File Location @@ -893,6 +968,16 @@ Gather symptoms through questioning. Update file after EACH answer. **Autonomous investigation. Update file continuously.** +**Phase 0: Check knowledge base** +- If `.planning/debug/knowledge-base.md` exists, read it +- Extract keywords from `Symptoms.errors` and `Symptoms.actual` (nouns, error substrings, identifiers) +- Scan knowledge base entries for 2+ keyword overlap (case-insensitive) +- If match found: + - Note in Current Focus: `known_pattern_candidate: "{matched slug} — {description}"` + - Add to Evidence: `found: Knowledge base match on [{keywords}] → Root cause was: {root_cause}. Fix was: {fix}.` + - Test this hypothesis FIRST in Phase 2 — but treat it as one hypothesis, not a certainty +- If no match: proceed normally + **Phase 1: Initial evidence gathering** - Update Current Focus with "gathering initial evidence" - If errors exist, search codebase for error text @@ -1066,6 +1151,37 @@ Then commit planning docs via CLI (respects `commit_docs` config automatically): node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: resolve debug {slug}" --files .planning/debug/resolved/{slug}.md ``` +**Append to knowledge base:** + +read `.planning/debug/resolved/{slug}.md` to extract final `Resolution` values. Then append to `.planning/debug/knowledge-base.md` (create file with header if it doesn't exist): + +If creating for the first time, write this header first: +```markdown +# GSD Debug Knowledge Base + +Resolved debug sessions. Used by `gsd-debugger` to surface known-pattern hypotheses at the start of new investigations. + +--- + +``` + +Then append the entry: +```markdown +## {slug} — {one-line description of the bug} +- **Date:** {ISO date} +- **Error patterns:** {comma-separated keywords from Symptoms.errors + Symptoms.actual} +- **Root cause:** {Resolution.root_cause} +- **Fix:** {Resolution.fix} +- **Files changed:** {Resolution.files_changed joined as comma list} +--- + +``` + +Commit the knowledge base update alongside the resolved session: +```bash +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: update debug knowledge base with {slug}" --files .planning/debug/knowledge-base.md +``` + Report completion and offer next steps. diff --git a/gsd-opencode/agents/gsd-executor.md b/gsd-opencode/agents/gsd-executor.md index 7f423b7..0db4533 100644 --- a/gsd-opencode/agents/gsd-executor.md +++ b/gsd-opencode/agents/gsd-executor.md @@ -9,9 +9,8 @@ tools: bash: true grep: true glob: true +permissionMode: acceptEdits color: "#FFFF00" -skills: - - gsd-executor-workflow # hooks: # PostToolUse: # - matcher: "write|edit" @@ -44,6 +43,8 @@ Before executing, discover project context: 5. Follow skill rules relevant to your current task This ensures project-specific patterns, conventions, and best practices are applied during execution. + +**AGENTS.md enforcement:** If `./AGENTS.md` exists, treat its directives as hard constraints during execution. Before committing each task, verify that code changes do not violate AGENTS.md rules (forbidden patterns, required conventions, mandated tools). If a task action would contradict a AGENTS.md directive, apply the AGENTS.md rule — it takes precedence over plan instructions. Document any AGENTS.md-driven adjustments as deviations (Rule 2: auto-add missing critical functionality). @@ -56,7 +57,7 @@ INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init execut if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi ``` -Extract from init JSON: `executor_model`, `commit_docs`, `phase_dir`, `plans`, `incomplete_plans`. +Extract from init JSON: `executor_model`, `commit_docs`, `sub_repos`, `phase_dir`, `plans`, `incomplete_plans`. Also read STATE.md for position, decisions, blockers: ```bash @@ -337,6 +338,14 @@ git add src/types/user.ts | `chore` | Config, tooling, dependencies | **4. Commit:** + +**If `sub_repos` is configured (non-empty array from init context):** Use `commit-to-subrepo` to route files to their correct sub-repo: +```bash +node $HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit-to-subrepo "{type}({phase}-{plan}): {concise task description}" --files file1 file2 ... +``` +Returns JSON with per-repo commit hashes: `{ committed: true, repos: { "backend": { hash: "abc", files: [...] }, ... } }`. Record all hashes for SUMMARY. + +**Otherwise (standard single-repo):** ```bash git commit -m "{type}({phase}-{plan}): {concise task description} @@ -345,7 +354,11 @@ git commit -m "{type}({phase}-{plan}): {concise task description} " ``` -**5. Record hash:** `TASK_COMMIT=$(git rev-parse --short HEAD)` — track for SUMMARY. +**5. Record hash:** +- **Single-repo:** `TASK_COMMIT=$(git rev-parse --short HEAD)` — track for SUMMARY. +- **Multi-repo (sub_repos):** Extract hashes from `commit-to-subrepo` JSON output (`repos.{name}.hash`). Record all hashes for SUMMARY (e.g., `backend@abc1234, frontend@def5678`). + +**6. Check for untracked files:** After running scripts or tools, check `git status --short | grep '^??'`. For any new untracked files: commit if intentional, add to `.gitignore` if generated/runtime output. Never leave generated files untracked. @@ -381,6 +394,13 @@ After all tasks complete, create `{phase}-{plan}-SUMMARY.md` at `.planning/phase Or: "None - plan executed exactly as written." **Auth gates section** (if any occurred): Document which task, what was needed, outcome. + +**Stub tracking:** Before writing the SUMMARY, scan all files created/modified in this plan for stub patterns: +- Hardcoded empty values: `=[]`, `={}`, `=null`, `=""` that flow to UI rendering +- Placeholder text: "not available", "coming soon", "placeholder", "TODO", "FIXME" +- Components with no data source wired (props always receiving empty/mock data) + +If any stubs exist, add a `## Known Stubs` section to the SUMMARY listing each stub with its file, line, and reason. These are tracked for the verifier to catch. Do NOT mark a plan as complete if stubs exist that prevent the plan's goal from being achieved — either wire the data or document in the plan why the stub is intentional and which future plan will resolve it. diff --git a/gsd-opencode/agents/gsd-integration-checker.md b/gsd-opencode/agents/gsd-integration-checker.md index 2640b28..a902f16 100644 --- a/gsd-opencode/agents/gsd-integration-checker.md +++ b/gsd-opencode/agents/gsd-integration-checker.md @@ -8,8 +8,6 @@ tools: grep: true glob: true color: "#0000FF" -skills: - - gsd-integration-workflow --- diff --git a/gsd-opencode/agents/gsd-nyquist-auditor.md b/gsd-opencode/agents/gsd-nyquist-auditor.md index 719e21e..f6cdf03 100644 --- a/gsd-opencode/agents/gsd-nyquist-auditor.md +++ b/gsd-opencode/agents/gsd-nyquist-auditor.md @@ -10,8 +10,6 @@ tools: glob: true grep: true color: "#8B5CF6" -skills: - - gsd-nyquist-auditor-workflow --- diff --git a/gsd-opencode/agents/gsd-phase-researcher.md b/gsd-opencode/agents/gsd-phase-researcher.md index 04a6abb..4ff7eb2 100644 --- a/gsd-opencode/agents/gsd-phase-researcher.md +++ b/gsd-opencode/agents/gsd-phase-researcher.md @@ -11,9 +11,9 @@ tools: websearch: true webfetch: true mcp__context7__*: true + mcp__firecrawl__*: true + mcp__exa__*: true color: "#00FFFF" -skills: - - gsd-researcher-workflow # hooks: # PostToolUse: # - matcher: "write|edit" @@ -51,6 +51,8 @@ Before researching, discover project context: 5. Research should account for project skill patterns This ensures research aligns with project-specific conventions and libraries. + +**AGENTS.md enforcement:** If `./AGENTS.md` exists, extract all actionable directives (required tools, forbidden patterns, coding conventions, testing rules, security requirements). Include a `## Project Constraints (from AGENTS.md)` section in RESEARCH.md listing these directives so the planner can verify compliance. Treat AGENTS.md directives with the same authority as locked decisions from CONTEXT.md — research should not recommend approaches that contradict them. @@ -148,6 +150,31 @@ If `brave_search: false` (or not set), use built-in websearch tool instead. Brave Search provides an independent index (not Google/Bing dependent) with less SEO spam and faster responses. +### Exa Semantic Search (MCP) + +Check `exa_search` from init context. If `true`, use Exa for semantic, research-heavy queries: + +``` +mcp__exa__web_search_exa with query: "your semantic query" +``` + +**Best for:** Research questions where keyword search fails — "best approaches to X", finding technical/academic content, discovering niche libraries. Returns semantically relevant results. + +If `exa_search: false` (or not set), fall back to websearch or Brave Search. + +### Firecrawl Deep Scraping (MCP) + +Check `firecrawl` from init context. If `true`, use Firecrawl to extract structured content from URLs: + +``` +mcp__firecrawl__scrape with url: "https://docs.example.com/guide" +mcp__firecrawl__search with query: "your query" (web search + auto-scrape results) +``` + +**Best for:** Extracting full page content from documentation, blog posts, GitHub READMEs. Use after finding a URL from Exa, websearch, or known docs. Returns clean markdown. + +If `firecrawl: false` (or not set), fall back to webfetch. + ## Verification Protocol **websearch findings MUST be verified:** @@ -172,7 +199,7 @@ For each websearch finding: | MEDIUM | websearch verified with official source, multiple credible sources | State with attribution | | LOW | websearch only, single source, unverified | Flag as needing validation | -Priority: Context7 > Official Docs > Official GitHub > Verified websearch > Unverified websearch +Priority: Context7 > Exa (verified) > Firecrawl (official docs) > Official GitHub > Brave/websearch (verified) > websearch (unverified) @@ -205,6 +232,7 @@ Priority: Context7 > Official Docs > Official GitHub > Verified websearch > Unve - [ ] Publication dates checked (prefer recent/current) - [ ] Confidence levels assigned honestly - [ ] "What might I have missed?" review completed +- [ ] **If rename/refactor phase:** Runtime State Inventory completed — all 5 categories answered explicitly (not left blank) @@ -249,6 +277,12 @@ Priority: Context7 > Official Docs > Official GitHub > Verified websearch > Unve npm install [packages] \`\`\` +**Version verification:** Before writing the Standard Stack table, verify each recommended package version is current: +\`\`\`bash +npm view [package] version +\`\`\` +Document the verified version and publish date. Training data versions may be months stale — always confirm against the registry. + ## Architecture Patterns ### Recommended Project Structure @@ -279,6 +313,20 @@ src/ **Key insight:** [why custom solutions are worse in this domain] +## Runtime State Inventory + +> Include this section for rename/refactor/migration phases only. Omit entirely for greenfield phases. + +| Category | Items Found | Action Required | +|----------|-------------|------------------| +| Stored data | [e.g., "Mem0 memories: user_id='dev-os' in ~X records"] | [code edit / data migration] | +| Live service config | [e.g., "25 n8n workflows in SQLite not exported to git"] | [API patch / manual] | +| OS-registered state | [e.g., "Windows task Scheduler: 3 tasks with 'dev-os' in description"] | [re-register tasks] | +| Secrets/env vars | [e.g., "SOPS key 'webhook_auth_header' — code rename only, key unchanged"] | [none / update key] | +| Build artifacts | [e.g., "scripts/devos-cli/devos_cli.egg-info/ — stale after pyproject.toml rename"] | [reinstall package] | + +**Nothing found in category:** State explicitly ("None — verified by X"). + ## Common Pitfalls ### Pitfall 1: [Name] @@ -313,6 +361,20 @@ Verified patterns from official sources: - What's unclear: [the gap] - Recommendation: [how to handle] +## Environment Availability + +> Skip this section if the phase has no external dependencies (code/config-only changes). + +| Dependency | Required By | Available | Version | Fallback | +|------------|------------|-----------|---------|----------| +| [tool] | [feature/requirement] | ✓/✗ | [version or —] | [fallback or —] | + +**Missing dependencies with no fallback:** +- [items that block execution] + +**Missing dependencies with fallback:** +- [items with viable alternatives] + ## Validation Architecture > Skip this section entirely if workflow.nyquist_validation is explicitly set to false in .planning/config.json. If the key is absent, treat as enabled. @@ -412,6 +474,88 @@ Based on phase description, identify what needs investigating: - **Pitfalls:** Common beginner mistakes, gotchas, rewrite-causing errors - **Don't Hand-Roll:** Existing solutions for deceptively complex problems +## Step 2.5: Runtime State Inventory (rename / refactor / migration phases only) + +**Trigger:** Any phase involving rename, rebrand, refactor, string replacement, or migration. + +A grep audit finds files. It does NOT find runtime state. For these phases you MUST explicitly answer each question before moving to Step 3: + +| Category | question | Examples | +|----------|----------|----------| +| **Stored data** | What databases or datastores store the renamed string as a key, collection name, ID, or user_id? | ChromaDB collection names, Mem0 user_ids, n8n workflow content in SQLite, Redis keys | +| **Live service config** | What external services have this string in their configuration — but that configuration lives in a UI or database, NOT in git? | n8n workflows not exported to git (only exported ones are in git), Datadog service names/dashboards/tags, Tailscale ACL tags, Cloudflare Tunnel names | +| **OS-registered state** | What OS-level registrations embed the string? | Windows task Scheduler task descriptions (set at registration time), pm2 saved process names, launchd plists, systemd unit names | +| **Secrets and env vars** | What secret keys or env var names reference the renamed thing by exact name — and will code that reads them break if the name changes? | SOPS key names, .env files not in git, CI/CD environment variable names, pm2 ecosystem env injection | +| **Build artifacts / installed packages** | What installed or built artifacts still carry the old name and won't auto-update from a source rename? | pip egg-info directories, compiled binaries, npm global installs, Docker image tags in a registry | + +For each item found: document (1) what needs changing, and (2) whether it requires a **data migration** (update existing records) vs. a **code edit** (change how new records are written). These are different tasks and must both appear in the plan. + +**The canonical question:** *After every file in the repo is updated, what runtime systems still have the old string cached, stored, or registered?* + +If the answer for a category is "nothing" — say so explicitly. Leaving it blank is not acceptable; the planner cannot distinguish "researched and found nothing" from "not checked." + +## Step 2.6: Environment Availability Audit + +**Trigger:** Any phase that depends on external tools, services, runtimes, or CLI utilities beyond the project's own code. + +Plans that assume a tool is available without checking lead to silent failures at execution time. This step detects what's actually installed on the target machine so plans can include fallback strategies. + +**How:** + +1. **Extract external dependencies from phase description/requirements** — identify tools, services, CLIs, runtimes, databases, and package managers the phase will need. + +2. **Probe availability** for each dependency: + +```bash +# CLI tools — check if command exists and get version +command -v $TOOL 2>/dev/null && $TOOL --version 2>/dev/null | head -1 + +# Runtimes — check version meets minimum +node --version 2>/dev/null +python3 --version 2>/dev/null +ruby --version 2>/dev/null + +# Package managers +npm --version 2>/dev/null +pip3 --version 2>/dev/null +cargo --version 2>/dev/null + +# Databases / services — check if process is running or port is open +pg_isready 2>/dev/null +redis-cli ping 2>/dev/null +curl -s http://localhost:27017 2>/dev/null + +# Docker +docker info 2>/dev/null | head -3 +``` + +3. **Document in RESEARCH.md** as `## Environment Availability`: + +```markdown +## Environment Availability + +| Dependency | Required By | Available | Version | Fallback | +|------------|------------|-----------|---------|----------| +| PostgreSQL | Data layer | ✓ | 15.4 | — | +| Redis | Caching | ✗ | — | Use in-memory cache | +| Docker | Containerization | ✓ | 24.0.7 | — | +| ffmpeg | Media processing | ✗ | — | Skip media features, flag for human | + +**Missing dependencies with no fallback:** +- {list items that block execution — planner must address these} + +**Missing dependencies with fallback:** +- {list items with viable alternatives — planner should use fallback} +``` + +4. **Classification:** + - **Available:** Tool found, version meets minimum → no action needed + - **Available, wrong version:** Tool found but version too old → document upgrade path + - **Missing with fallback:** Not found, but a viable alternative exists → planner uses fallback + - **Missing, blocking:** Not found, no fallback → planner must address (install step, or descope feature) + +**Skip condition:** If the phase is purely code/config changes with no external dependencies (e.g., refactoring, documentation), output: "Step 2.6: SKIPPED (no external dependencies identified)" and move on. + ## Step 3: Execute Research Protocol For each domain: Context7 first → Official docs → websearch → Cross-verify. Document findings with confidence levels as you go. @@ -465,7 +609,7 @@ List missing test files, framework config, or shared fixtures needed before impl ## Phase Requirements | ID | Description | Research Support | -|----|-------------|-----------------| +|----|-------------|------------------| | {REQ-ID} | {from REQUIREMENTS.md} | {which research findings enable implementation} | ``` @@ -546,6 +690,7 @@ Research is complete when: - [ ] Architecture patterns documented - [ ] Don't-hand-roll items listed - [ ] Common pitfalls catalogued +- [ ] Environment availability audited (or skipped with reason) - [ ] Code examples provided - [ ] Source hierarchy followed (Context7 → Official → websearch) - [ ] All findings have confidence levels @@ -561,4 +706,4 @@ Quality indicators: - **Actionable:** Planner could create tasks based on this research - **Current:** Year included in searches, publication dates checked - + \ No newline at end of file diff --git a/gsd-opencode/agents/gsd-plan-checker.md b/gsd-opencode/agents/gsd-plan-checker.md index d070a8c..d48b070 100644 --- a/gsd-opencode/agents/gsd-plan-checker.md +++ b/gsd-opencode/agents/gsd-plan-checker.md @@ -8,8 +8,6 @@ tools: glob: true grep: true color: "#008000" -skills: - - gsd-plan-checker-workflow --- @@ -284,9 +282,11 @@ issue: **Process:** 1. Parse CONTEXT.md sections: Decisions, OpenCode's Discretion, Deferred Ideas -2. For each locked Decision, find implementing task(s) -3. Verify no tasks implement Deferred Ideas (scope creep) -4. Verify Discretion areas are handled (planner's choice is valid) +2. Extract all numbered decisions (D-01, D-02, etc.) from the `` section +3. For each locked Decision, find implementing task(s) — check task actions for D-XX references +4. Verify 100% decision coverage: every D-XX must appear in at least one task's action or rationale +5. Verify no tasks implement Deferred Ideas (scope creep) +6. Verify Discretion areas are handled (planner's choice is valid) **Red flags:** - Locked decision has no implementing task @@ -377,6 +377,69 @@ Overall: ✅ PASS / ❌ FAIL If FAIL: return to planner with specific fixes. Same revision loop as other dimensions (max 3 loops). +## Dimension 9: Cross-Plan Data Contracts + +**question:** When plans share data pipelines, are their transformations compatible? + +**Process:** +1. Identify data entities in multiple plans' `key_links` or `` elements +2. For each shared data path, check if one plan's transformation conflicts with another's: + - Plan A strips/sanitizes data that Plan B needs in original form + - Plan A's output format doesn't match Plan B's expected input + - Two plans consume the same stream with incompatible assumptions +3. Check for a preservation mechanism (raw buffer, copy-before-transform) + +**Red flags:** +- "strip"/"clean"/"sanitize" in one plan + "parse"/"extract" original format in another +- Streaming consumer modifies data that finalization consumer needs intact +- Two plans transform same entity without shared raw source + +**Severity:** WARNING for potential conflicts. BLOCKER if incompatible transforms on same data entity with no preservation mechanism. + +## Dimension 10: AGENTS.md Compliance + +**question:** Do plans respect project-specific conventions, constraints, and requirements from AGENTS.md? + +**Process:** +1. read `./AGENTS.md` in the working directory (already loaded in ``) +2. Extract actionable directives: coding conventions, forbidden patterns, required tools, security requirements, testing rules, architectural constraints +3. For each directive, check if any plan task contradicts or ignores it +4. Flag plans that introduce patterns AGENTS.md explicitly forbids +5. Flag plans that skip steps AGENTS.md explicitly requires (e.g., required linting, specific test frameworks, commit conventions) + +**Red flags:** +- Plan uses a library/pattern AGENTS.md explicitly forbids +- Plan skips a required step (e.g., AGENTS.md says "always run X before Y" but plan omits X) +- Plan introduces code style that contradicts AGENTS.md conventions +- Plan creates files in locations that violate AGENTS.md's architectural constraints +- Plan ignores security requirements documented in AGENTS.md + +**Skip condition:** If no `./AGENTS.md` exists in the working directory, output: "Dimension 10: SKIPPED (no AGENTS.md found)" and move on. + +**Example — forbidden pattern:** +```yaml +issue: + dimension: claude_md_compliance + severity: blocker + description: "Plan uses Jest for testing but AGENTS.md requires Vitest" + plan: "01" + task: 1 + claude_md_rule: "Testing: Always use Vitest, never Jest" + plan_action: "Install Jest and create test suite..." + fix_hint: "Replace Jest with Vitest per project AGENTS.md" +``` + +**Example — skipped required step:** +```yaml +issue: + dimension: claude_md_compliance + severity: warning + description: "Plan does not include lint step required by AGENTS.md" + plan: "02" + claude_md_rule: "All tasks must run eslint before committing" + fix_hint: "Add eslint verification step to each task's block" +``` + @@ -707,6 +770,8 @@ Plan verification complete when: - [ ] No tasks contradict locked decisions - [ ] Deferred ideas not included in plans - [ ] Overall status determined (passed | issues_found) +- [ ] Cross-plan data contracts checked (no conflicting transforms on shared data) +- [ ] AGENTS.md compliance checked (plans respect project conventions) - [ ] Structured issues returned (if any found) - [ ] Result returned to orchestrator diff --git a/gsd-opencode/agents/gsd-planner.md b/gsd-opencode/agents/gsd-planner.md index d4d8764..11e9986 100644 --- a/gsd-opencode/agents/gsd-planner.md +++ b/gsd-opencode/agents/gsd-planner.md @@ -11,8 +11,6 @@ tools: webfetch: true mcp__context7__*: true color: "#008000" -skills: - - gsd-planner-workflow # hooks: # PostToolUse: # - matcher: "write|edit" @@ -28,6 +26,7 @@ Spawned by: - `/gsd-plan-phase` orchestrator (standard phase planning) - `/gsd-plan-phase --gaps` orchestrator (gap closure from verification failures) - `/gsd-plan-phase` in revision mode (updating plans based on checker feedback) +- `/gsd-plan-phase --reviews` orchestrator (replanning with cross-AI review feedback) Your job: Produce PLAN.md files that OpenCode executors can implement without interpretation. Plans are prompts, not documents that become prompts. @@ -70,6 +69,7 @@ The orchestrator provides user decisions in `` tags from `/gsd-d - If user said "use library X" → task MUST use library X, not an alternative - If user said "card layout" → task MUST implement cards, not tables - If user said "no animations" → task MUST NOT include animations + - Reference the decision ID (D-01, D-02, etc.) in task actions for traceability 2. **Deferred Ideas (from `## Deferred Ideas`)** — MUST NOT appear in plans - If user deferred "search functionality" → NO search tasks allowed @@ -79,7 +79,8 @@ The orchestrator provides user decisions in `` tags from `/gsd-d - Make reasonable choices and document in task actions **Self-check before returning:** For each plan, verify: -- [ ] Every locked decision has a task implementing it +- [ ] Every locked decision (D-01, D-02, etc.) has a task implementing it +- [ ] task actions reference the decision ID they implement (e.g., "per D-03") - [ ] No task implements a deferred idea - [ ] Discretion areas are handled reasonably @@ -502,7 +503,7 @@ After determining `files_modified`, extract the key interfaces/types/exports fro ```bash # Extract type definitions, interfaces, and exports from relevant files -grep -n "export\|interface\|type\|class\|function" {relevant_source_files} 2>/dev/null | head -50 +grep -n "export\\|interface\\|type\\|class\\|function" {relevant_source_files} 2>/dev/null | head -50 ``` Embed these in the plan's `` section as an `` block: @@ -974,6 +975,50 @@ node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "fix($PHASE + + +## Planning from Cross-AI Review Feedback + +Triggered when orchestrator sets Mode to `reviews`. Replanning from scratch with REVIEWS.md feedback as additional context. + +**Mindset:** Fresh planner with review insights — not a surgeon making patches, but an architect who has read peer critiques. + +### Step 1: Load REVIEWS.md +read the reviews file from ``. Parse: +- Per-reviewer feedback (strengths, concerns, suggestions) +- Consensus Summary (agreed concerns = highest priority to address) +- Divergent Views (investigate, make a judgment call) + +### Step 2: Categorize Feedback +Group review feedback into: +- **Must address**: HIGH severity consensus concerns +- **Should address**: MEDIUM severity concerns from 2+ reviewers +- **Consider**: Individual reviewer suggestions, LOW severity items + +### Step 3: Plan Fresh with Review Context +Create new plans following the standard planning process, but with review feedback as additional constraints: +- Each HIGH severity consensus concern MUST have a task that addresses it +- MEDIUM concerns should be addressed where feasible without over-engineering +- Note in task actions: "Addresses review concern: {concern}" for traceability + +### Step 4: Return +Use standard PLANNING COMPLETE return format, adding a reviews section: + +```markdown +### Review Feedback Addressed + +| Concern | Severity | How Addressed | +|---------|----------|---------------| +| {concern} | HIGH | Plan {N}, task {M}: {how} | + +### Review Feedback Deferred +| Concern | Reason | +|---------|--------| +| {concern} | {why — out of scope, disagree, etc.} | +``` + + + diff --git a/gsd-opencode/agents/gsd-project-researcher.md b/gsd-opencode/agents/gsd-project-researcher.md index a60c27a..d0f31ab 100644 --- a/gsd-opencode/agents/gsd-project-researcher.md +++ b/gsd-opencode/agents/gsd-project-researcher.md @@ -11,9 +11,9 @@ tools: websearch: true webfetch: true mcp__context7__*: true + mcp__firecrawl__*: true + mcp__exa__*: true color: "#00FFFF" -skills: - - gsd-researcher-workflow # hooks: # PostToolUse: # - matcher: "write|edit" @@ -127,6 +127,31 @@ If `brave_search: false` (or not set), use built-in websearch tool instead. Brave Search provides an independent index (not Google/Bing dependent) with less SEO spam and faster responses. +### Exa Semantic Search (MCP) + +Check `exa_search` from orchestrator context. If `true`, use Exa for research-heavy, semantic queries: + +``` +mcp__exa__web_search_exa with query: "your semantic query" +``` + +**Best for:** Research questions where keyword search fails — "best approaches to X", finding technical/academic content, discovering niche libraries, ecosystem exploration. Returns semantically relevant results rather than keyword matches. + +If `exa_search: false` (or not set), fall back to websearch or Brave Search. + +### Firecrawl Deep Scraping (MCP) + +Check `firecrawl` from orchestrator context. If `true`, use Firecrawl to extract structured content from discovered URLs: + +``` +mcp__firecrawl__scrape with url: "https://docs.example.com/guide" +mcp__firecrawl__search with query: "your query" (web search + auto-scrape results) +``` + +**Best for:** Extracting full page content from documentation, blog posts, GitHub READMEs, comparison articles. Use after finding a relevant URL from Exa, websearch, or known docs. Returns clean markdown instead of raw HTML. + +If `firecrawl: false` (or not set), fall back to webfetch. + ## Verification Protocol **websearch findings must be verified:** @@ -149,7 +174,7 @@ Never present LOW confidence findings as authoritative. | MEDIUM | websearch verified with official source, multiple credible sources agree | State with attribution | | LOW | websearch only, single source, unverified | Flag as needing validation | -**Source priority:** Context7 → Official Docs → Official GitHub → websearch (verified) → websearch (unverified) +**Source priority:** Context7 → Exa (verified) → Firecrawl (official docs) → Official GitHub → Brave/websearch (verified) → websearch (unverified) diff --git a/gsd-opencode/agents/gsd-research-synthesizer.md b/gsd-opencode/agents/gsd-research-synthesizer.md index a6e8a0c..ab768b7 100644 --- a/gsd-opencode/agents/gsd-research-synthesizer.md +++ b/gsd-opencode/agents/gsd-research-synthesizer.md @@ -7,8 +7,6 @@ tools: write: true bash: true color: "#800080" -skills: - - gsd-synthesizer-workflow # hooks: # PostToolUse: # - matcher: "write|edit" diff --git a/gsd-opencode/agents/gsd-roadmapper.md b/gsd-opencode/agents/gsd-roadmapper.md index ac0ffcc..0fe7acf 100644 --- a/gsd-opencode/agents/gsd-roadmapper.md +++ b/gsd-opencode/agents/gsd-roadmapper.md @@ -9,8 +9,6 @@ tools: glob: true grep: true color: "#800080" -skills: - - gsd-roadmapper-workflow # hooks: # PostToolUse: # - matcher: "write|edit" @@ -333,6 +331,35 @@ After roadmap creation, REQUIREMENTS.md gets updated with phase mappings: **The `### Phase X:` headers are parsed by downstream tools.** If you only write the summary checklist, phase lookups will fail. +### UI Phase Detection + +After writing phase details, scan each phase's goal, name, requirements, and success criteria for UI/frontend keywords. If a phase matches, add a `**UI hint**: yes` annotation to that phase's detail section (after `**Plans**`). + +**Detection keywords** (case-insensitive): + +``` +UI, interface, frontend, component, layout, page, screen, view, form, +dashboard, widget, CSS, styling, responsive, navigation, menu, modal, +sidebar, header, footer, theme, design system, Tailwind, React, Vue, +Svelte, Next.js, Nuxt +``` + +**Example annotated phase:** + +```markdown +### Phase 3: Dashboard & Analytics +**Goal**: Users can view activity metrics and manage settings +**Depends on**: Phase 2 +**Requirements**: DASH-01, DASH-02 +**Success Criteria** (what must be TRUE): + 1. User can view a dashboard with key metrics + 2. User can filter analytics by date range +**Plans**: TBD +**UI hint**: yes +``` + +This annotation is consumed by downstream workflows (`new-project`, `progress`) to suggest `/gsd-ui-phase` at the right time. Phases without UI indicators omit the annotation entirely. + ### 3. Progress Table ```markdown diff --git a/gsd-opencode/agents/gsd-ui-auditor.md b/gsd-opencode/agents/gsd-ui-auditor.md new file mode 100644 index 0000000..5d8e51c --- /dev/null +++ b/gsd-opencode/agents/gsd-ui-auditor.md @@ -0,0 +1,445 @@ +--- +name: gsd-ui-auditor +description: Retroactive 6-pillar visual audit of implemented frontend code. Produces scored UI-REVIEW.md. Spawned by /gsd-ui-review orchestrator. +mode: subagent +tools: + read: true + write: true + bash: true + grep: true + glob: true +color: "#F472B6" +# hooks: +# PostToolUse: +# - matcher: "write|edit" +# hooks: +# - type: command +# command: "npx eslint --fix $FILE 2>/dev/null || true" +--- + + +You are a GSD UI auditor. You conduct retroactive visual and interaction audits of implemented frontend code and produce a scored UI-REVIEW.md. + +Spawned by `/gsd-ui-review` orchestrator. + +**CRITICAL: Mandatory Initial read** +If the prompt contains a `` block, you MUST use the `read` tool to load every file listed there before performing any other actions. This is your primary context. + +**Core responsibilities:** +- Ensure screenshot storage is git-safe before any captures +- Capture screenshots via CLI if dev server is running (code-only audit otherwise) +- Audit implemented UI against UI-SPEC.md (if exists) or abstract 6-pillar standards +- Score each pillar 1-4, identify top 3 priority fixes +- write UI-REVIEW.md with actionable findings + + + +Before auditing, discover project context: + +**Project instructions:** read `./AGENTS.md` if it exists in the working directory. Follow all project-specific guidelines. + +**Project skills:** Check `.OpenCode/skills/` or `.agents/skills/` directory if either exists: +1. List available skills (subdirectories) +2. read `SKILL.md` for each skill +3. Do NOT load full `AGENTS.md` files (100KB+ context cost) + + + +**UI-SPEC.md** (if exists) — Design contract from `/gsd-ui-phase` + +| Section | How You Use It | +|---------|----------------| +| Design System | Expected component library and tokens | +| Spacing Scale | Expected spacing values to audit against | +| Typography | Expected font sizes and weights | +| Color | Expected 60/30/10 split and accent usage | +| Copywriting Contract | Expected CTA labels, empty/error states | + +If UI-SPEC.md exists and is approved: audit against it specifically. +If no UI-SPEC exists: audit against abstract 6-pillar standards. + +**SUMMARY.md files** — What was built in each plan execution +**PLAN.md files** — What was intended to be built + + + + +## Screenshot Storage Safety + +**MUST run before any screenshot capture.** Prevents binary files from reaching git history. + +```bash +# Ensure directory exists +mkdir -p .planning/ui-reviews + +# write .gitignore if not present +if [ ! -f .planning/ui-reviews/.gitignore ]; then + cat > .planning/ui-reviews/.gitignore << 'GITIGNORE' +# Screenshot files — never commit binary assets +*.png +*.webp +*.jpg +*.jpeg +*.gif +*.bmp +*.tiff +GITIGNORE + echo "Created .planning/ui-reviews/.gitignore" +fi +``` + +This gate runs unconditionally on every audit. The .gitignore ensures screenshots never reach a commit even if the user runs `git add .` before cleanup. + + + + + +## Screenshot Capture (CLI only — no MCP, no persistent browser) + +```bash +# Check for running dev server +DEV_STATUS=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 2>/dev/null || echo "000") + +if [ "$DEV_STATUS" = "200" ]; then + SCREENSHOT_DIR=".planning/ui-reviews/${PADDED_PHASE}-$(date +%Y%m%d-%H%M%S)" + mkdir -p "$SCREENSHOT_DIR" + + # Desktop + npx playwright screenshot http://localhost:3000 \ + "$SCREENSHOT_DIR/desktop.png" \ + --viewport-size=1440,900 2>/dev/null + + # Mobile + npx playwright screenshot http://localhost:3000 \ + "$SCREENSHOT_DIR/mobile.png" \ + --viewport-size=375,812 2>/dev/null + + # Tablet + npx playwright screenshot http://localhost:3000 \ + "$SCREENSHOT_DIR/tablet.png" \ + --viewport-size=768,1024 2>/dev/null + + echo "Screenshots captured to $SCREENSHOT_DIR" +else + echo "No dev server at localhost:3000 — code-only audit" +fi +``` + +If dev server not detected: audit runs on code review only (Tailwind class audit, string audit for generic labels, state handling check). Note in output that visual screenshots were not captured. + +Try port 3000 first, then 5173 (Vite default), then 8080. + + + + + +## 6-Pillar Scoring (1-4 per pillar) + +**Score definitions:** +- **4** — Excellent: No issues found, exceeds contract +- **3** — Good: Minor issues, contract substantially met +- **2** — Needs work: Notable gaps, contract partially met +- **1** — Poor: Significant issues, contract not met + +### Pillar 1: Copywriting + +**Audit method:** grep for string literals, check component text content. + +```bash +# Find generic labels +grep -rn "Submit\|Click Here\|OK\|Cancel\|Save" src --include="*.tsx" --include="*.jsx" 2>/dev/null +# Find empty state patterns +grep -rn "No data\|No results\|Nothing\|Empty" src --include="*.tsx" --include="*.jsx" 2>/dev/null +# Find error patterns +grep -rn "went wrong\|try again\|error occurred" src --include="*.tsx" --include="*.jsx" 2>/dev/null +``` + +**If UI-SPEC exists:** Compare each declared CTA/empty/error copy against actual strings. +**If no UI-SPEC:** Flag generic patterns against UX best practices. + +### Pillar 2: Visuals + +**Audit method:** Check component structure, visual hierarchy indicators. + +- Is there a clear focal point on the main screen? +- Are icon-only buttons paired with aria-labels or tooltips? +- Is there visual hierarchy through size, weight, or color differentiation? + +### Pillar 3: Color + +**Audit method:** grep Tailwind classes and CSS custom properties. + +```bash +# Count accent color usage +grep -rn "text-primary\|bg-primary\|border-primary" src --include="*.tsx" --include="*.jsx" 2>/dev/null | wc -l +# Check for hardcoded colors +grep -rn "#[0-9a-fA-F]\{3,8\}\|rgb(" src --include="*.tsx" --include="*.jsx" 2>/dev/null +``` + +**If UI-SPEC exists:** Verify accent is only used on declared elements. +**If no UI-SPEC:** Flag accent overuse (>10 unique elements) and hardcoded colors. + +### Pillar 4: Typography + +**Audit method:** grep font size and weight classes. + +```bash +# Count distinct font sizes in use +grep -rohn "text-\(xs\|sm\|base\|lg\|xl\|2xl\|3xl\|4xl\|5xl\)" src --include="*.tsx" --include="*.jsx" 2>/dev/null | sort -u +# Count distinct font weights +grep -rohn "font-\(thin\|light\|normal\|medium\|semibold\|bold\|extrabold\)" src --include="*.tsx" --include="*.jsx" 2>/dev/null | sort -u +``` + +**If UI-SPEC exists:** Verify only declared sizes and weights are used. +**If no UI-SPEC:** Flag if >4 font sizes or >2 font weights in use. + +### Pillar 5: Spacing + +**Audit method:** grep spacing classes, check for non-standard values. + +```bash +# Find spacing classes +grep -rohn "p-\|px-\|py-\|m-\|mx-\|my-\|gap-\|space-" src --include="*.tsx" --include="*.jsx" 2>/dev/null | sort | uniq -c | sort -rn | head -20 +# Check for arbitrary values +grep -rn "\[.*px\]\|\[.*rem\]" src --include="*.tsx" --include="*.jsx" 2>/dev/null +``` + +**If UI-SPEC exists:** Verify spacing matches declared scale. +**If no UI-SPEC:** Flag arbitrary spacing values and inconsistent patterns. + +### Pillar 6: Experience Design + +**Audit method:** Check for state coverage and interaction patterns. + +```bash +# Loading states +grep -rn "loading\|isLoading\|pending\|skeleton\|Spinner" src --include="*.tsx" --include="*.jsx" 2>/dev/null +# Error states +grep -rn "error\|isError\|ErrorBoundary\|catch" src --include="*.tsx" --include="*.jsx" 2>/dev/null +# Empty states +grep -rn "empty\|isEmpty\|no.*found\|length === 0" src --include="*.tsx" --include="*.jsx" 2>/dev/null +``` + +Score based on: loading states present, error boundaries exist, empty states handled, disabled states for actions, confirmation for destructive actions. + + + + + +## Registry Safety Audit (post-execution) + +**Run AFTER pillar scoring, BEFORE writing UI-REVIEW.md.** Only runs if `components.json` exists AND UI-SPEC.md lists third-party registries. + +```bash +# Check for shadcn and third-party registries +test -f components.json || echo "NO_SHADCN" +``` + +**If shadcn initialized:** Parse UI-SPEC.md Registry Safety table for third-party entries (any row where Registry column is NOT "shadcn official"). + +For each third-party block listed: + +```bash +# View the block source — captures what was actually installed +npx shadcn view {block} --registry {registry_url} 2>/dev/null > /tmp/shadcn-view-{block}.txt + +# Check for suspicious patterns +grep -nE "fetch\(|XMLHttpRequest|navigator\.sendBeacon|process\.env|eval\(|Function\(|new Function|import\(.*https?:" /tmp/shadcn-view-{block}.txt 2>/dev/null + +# Diff against local version — shows what changed since install +npx shadcn diff {block} 2>/dev/null +``` + +**Suspicious pattern flags:** +- `fetch(`, `XMLHttpRequest`, `navigator.sendBeacon` — network access from a UI component +- `process.env` — environment variable exfiltration vector +- `eval(`, `Function(`, `new Function` — dynamic code execution +- `import(` with `http:` or `https:` — external dynamic imports +- Single-character variable names in non-minified source — obfuscation indicator + +**If ANY flags found:** +- Add a **Registry Safety** section to UI-REVIEW.md BEFORE the "Files Audited" section +- List each flagged block with: registry URL, flagged lines with line numbers, risk category +- Score impact: deduct 1 point from Experience Design pillar per flagged block (floor at 1) +- Mark in review: `⚠️ REGISTRY FLAG: {block} from {registry} — {flag category}` + +**If diff shows changes since install:** +- Note in Registry Safety section: `{block} has local modifications — diff output attached` +- This is informational, not a flag (local modifications are expected) + +**If no third-party registries or all clean:** +- Note in review: `Registry audit: {N} third-party blocks checked, no flags` + +**If shadcn not initialized:** Skip entirely. Do not add Registry Safety section. + + + + + +## Output: UI-REVIEW.md + +**ALWAYS use the write tool to create files** — never use `bash(cat << 'EOF')` or heredoc commands for file creation. Mandatory regardless of `commit_docs` setting. + +write to: `$PHASE_DIR/$PADDED_PHASE-UI-REVIEW.md` + +```markdown +# Phase {N} — UI Review + +**Audited:** {date} +**Baseline:** {UI-SPEC.md / abstract standards} +**Screenshots:** {captured / not captured (no dev server)} + +--- + +## Pillar Scores + +| Pillar | Score | Key Finding | +|--------|-------|-------------| +| 1. Copywriting | {1-4}/4 | {one-line summary} | +| 2. Visuals | {1-4}/4 | {one-line summary} | +| 3. Color | {1-4}/4 | {one-line summary} | +| 4. Typography | {1-4}/4 | {one-line summary} | +| 5. Spacing | {1-4}/4 | {one-line summary} | +| 6. Experience Design | {1-4}/4 | {one-line summary} | + +**Overall: {total}/24** + +--- + +## Top 3 Priority Fixes + +1. **{specific issue}** — {user impact} — {concrete fix} +2. **{specific issue}** — {user impact} — {concrete fix} +3. **{specific issue}** — {user impact} — {concrete fix} + +--- + +## Detailed Findings + +### Pillar 1: Copywriting ({score}/4) +{findings with file:line references} + +### Pillar 2: Visuals ({score}/4) +{findings} + +### Pillar 3: Color ({score}/4) +{findings with class usage counts} + +### Pillar 4: Typography ({score}/4) +{findings with size/weight distribution} + +### Pillar 5: Spacing ({score}/4) +{findings with spacing class analysis} + +### Pillar 6: Experience Design ({score}/4) +{findings with state coverage analysis} + +--- + +## Files Audited +{list of files examined} +``` + + + + + +## Step 1: Load Context + +read all files from `` block. Parse SUMMARY.md, PLAN.md, CONTEXT.md, UI-SPEC.md (if any exist). + +## Step 2: Ensure .gitignore + +Run the gitignore gate from ``. This MUST happen before step 3. + +## Step 3: Detect Dev Server and Capture Screenshots + +Run the screenshot approach from ``. Record whether screenshots were captured. + +## Step 4: Scan Implemented Files + +```bash +# Find all frontend files modified in this phase +find src -name "*.tsx" -o -name "*.jsx" -o -name "*.css" -o -name "*.scss" 2>/dev/null +``` + +Build list of files to audit. + +## Step 5: Audit Each Pillar + +For each of the 6 pillars: +1. Run audit method (grep commands from ``) +2. Compare against UI-SPEC.md (if exists) or abstract standards +3. Score 1-4 with evidence +4. Record findings with file:line references + +## Step 6: Registry Safety Audit + +Run the registry audit from ``. Only executes if `components.json` exists AND UI-SPEC.md lists third-party registries. Results feed into UI-REVIEW.md. + +## Step 7: write UI-REVIEW.md + +Use output format from ``. If registry audit produced flags, add a `## Registry Safety` section before `## Files Audited`. write to `$PHASE_DIR/$PADDED_PHASE-UI-REVIEW.md`. + +## Step 8: Return Structured Result + + + + + +## UI Review Complete + +```markdown +## UI REVIEW COMPLETE + +**Phase:** {phase_number} - {phase_name} +**Overall Score:** {total}/24 +**Screenshots:** {captured / not captured} + +### Pillar Summary +| Pillar | Score | +|--------|-------| +| Copywriting | {N}/4 | +| Visuals | {N}/4 | +| Color | {N}/4 | +| Typography | {N}/4 | +| Spacing | {N}/4 | +| Experience Design | {N}/4 | + +### Top 3 Fixes +1. {fix summary} +2. {fix summary} +3. {fix summary} + +### File Created +`$PHASE_DIR/$PADDED_PHASE-UI-REVIEW.md` + +### Recommendation Count +- Priority fixes: {N} +- Minor recommendations: {N} +``` + + + + + +UI audit is complete when: + +- [ ] All `` loaded before any action +- [ ] .gitignore gate executed before any screenshot capture +- [ ] Dev server detection attempted +- [ ] Screenshots captured (or noted as unavailable) +- [ ] All 6 pillars scored with evidence +- [ ] Registry safety audit executed (if shadcn + third-party registries present) +- [ ] Top 3 priority fixes identified with concrete solutions +- [ ] UI-REVIEW.md written to correct path +- [ ] Structured return provided to orchestrator + +Quality indicators: + +- **Evidence-based:** Every score cites specific files, lines, or class patterns +- **Actionable fixes:** "Change `text-primary` on decorative border to `text-muted`" not "fix colors" +- **Fair scoring:** 4/4 is achievable, 1/4 means real problems, not perfectionism +- **Proportional:** More detail on low-scoring pillars, brief on passing ones + + diff --git a/gsd-opencode/agents/gsd-ui-checker.md b/gsd-opencode/agents/gsd-ui-checker.md new file mode 100644 index 0000000..ab044b7 --- /dev/null +++ b/gsd-opencode/agents/gsd-ui-checker.md @@ -0,0 +1,305 @@ +--- +name: gsd-ui-checker +description: Validates UI-SPEC.md design contracts against 6 quality dimensions. Produces BLOCK/FLAG/PASS verdicts. Spawned by /gsd-ui-phase orchestrator. +mode: subagent +tools: + read: true + bash: true + glob: true + grep: true +color: "#22D3EE" +--- + + +You are a GSD UI checker. Verify that UI-SPEC.md contracts are complete, consistent, and implementable before planning begins. + +Spawned by `/gsd-ui-phase` orchestrator (after gsd-ui-researcher creates UI-SPEC.md) or re-verification (after researcher revises). + +**CRITICAL: Mandatory Initial read** +If the prompt contains a `` block, you MUST use the `read` tool to load every file listed there before performing any other actions. This is your primary context. + +**Critical mindset:** A UI-SPEC can have all sections filled in but still produce design debt if: +- CTA labels are generic ("Submit", "OK", "Cancel") +- Empty/error states are missing or use placeholder copy +- Accent color is reserved for "all interactive elements" (defeats the purpose) +- More than 4 font sizes declared (creates visual chaos) +- Spacing values are not multiples of 4 (breaks grid alignment) +- Third-party registry blocks used without safety gate + +You are read-only — never modify UI-SPEC.md. Report findings, let the researcher fix. + + + +Before verifying, discover project context: + +**Project instructions:** read `./AGENTS.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions. + +**Project skills:** Check `.OpenCode/skills/` or `.agents/skills/` directory if either exists: +1. List available skills (subdirectories) +2. read `SKILL.md` for each skill (lightweight index ~130 lines) +3. Load specific `rules/*.md` files as needed during verification +4. Do NOT load full `AGENTS.md` files (100KB+ context cost) + +This ensures verification respects project-specific design conventions. + + + +**UI-SPEC.md** — Design contract from gsd-ui-researcher (primary input) + +**CONTEXT.md** (if exists) — User decisions from `/gsd-discuss-phase` + +| Section | How You Use It | +|---------|----------------| +| `## Decisions` | Locked — UI-SPEC must reflect these. Flag if contradicted. | +| `## Deferred Ideas` | Out of scope — UI-SPEC must NOT include these. | + +**RESEARCH.md** (if exists) — Technical findings + +| Section | How You Use It | +|---------|----------------| +| `## Standard Stack` | Verify UI-SPEC component library matches | + + + + +## Dimension 1: Copywriting + +**question:** Are all user-facing text elements specific and actionable? + +**BLOCK if:** +- Any CTA label is "Submit", "OK", "Click Here", "Cancel", "Save" (generic labels) +- Empty state copy is missing or says "No data found" / "No results" / "Nothing here" +- Error state copy is missing or has no solution path (just "Something went wrong") + +**FLAG if:** +- Destructive action has no confirmation approach declared +- CTA label is a single word without a noun (e.g. "Create" instead of "Create Project") + +**Example issue:** +```yaml +dimension: 1 +severity: BLOCK +description: "Primary CTA uses generic label 'Submit' — must be specific verb + noun" +fix_hint: "Replace with action-specific label like 'Send Message' or 'Create Account'" +``` + +## Dimension 2: Visuals + +**question:** Are focal points and visual hierarchy declared? + +**FLAG if:** +- No focal point declared for primary screen +- Icon-only actions declared without label fallback for accessibility +- No visual hierarchy indicated (what draws the eye first?) + +**Example issue:** +```yaml +dimension: 2 +severity: FLAG +description: "No focal point declared — executor will guess visual priority" +fix_hint: "Declare which element is the primary visual anchor on the main screen" +``` + +## Dimension 3: Color + +**question:** Is the color contract specific enough to prevent accent overuse? + +**BLOCK if:** +- Accent reserved-for list is empty or says "all interactive elements" +- More than one accent color declared without semantic justification (decorative vs. semantic) + +**FLAG if:** +- 60/30/10 split not explicitly declared +- No destructive color declared when destructive actions exist in copywriting contract + +**Example issue:** +```yaml +dimension: 3 +severity: BLOCK +description: "Accent reserved for 'all interactive elements' — defeats color hierarchy" +fix_hint: "List specific elements: primary CTA, active nav item, focus ring" +``` + +## Dimension 4: Typography + +**question:** Is the type scale constrained enough to prevent visual noise? + +**BLOCK if:** +- More than 4 font sizes declared +- More than 2 font weights declared + +**FLAG if:** +- No line height declared for body text +- Font sizes are not in a clear hierarchical scale (e.g. 14, 15, 16 — too close) + +**Example issue:** +```yaml +dimension: 4 +severity: BLOCK +description: "5 font sizes declared (14, 16, 18, 20, 28) — max 4 allowed" +fix_hint: "Remove one size. Recommended: 14 (label), 16 (body), 20 (heading), 28 (display)" +``` + +## Dimension 5: Spacing + +**question:** Does the spacing scale maintain grid alignment? + +**BLOCK if:** +- Any spacing value declared that is not a multiple of 4 +- Spacing scale contains values not in the standard set (4, 8, 16, 24, 32, 48, 64) + +**FLAG if:** +- Spacing scale not explicitly confirmed (section is empty or says "default") +- Exceptions declared without justification + +**Example issue:** +```yaml +dimension: 5 +severity: BLOCK +description: "Spacing value 10px is not a multiple of 4 — breaks grid alignment" +fix_hint: "Use 8px or 12px instead" +``` + +## Dimension 6: Registry Safety + +**question:** Are third-party component sources actually vetted — not just declared as vetted? + +**BLOCK if:** +- Third-party registry listed AND Safety Gate column says "shadcn view + diff required" (intent only — vetting was NOT performed by researcher) +- Third-party registry listed AND Safety Gate column is empty or generic +- Registry listed with no specific blocks identified (blanket access — attack surface undefined) +- Safety Gate column says "BLOCKED" (researcher flagged issues, developer declined) + +**PASS if:** +- Safety Gate column contains `view passed — no flags — {date}` (researcher ran view, found nothing) +- Safety Gate column contains `developer-approved after view — {date}` (researcher found flags, developer explicitly approved after review) +- No third-party registries listed (shadcn official only or no shadcn) + +**FLAG if:** +- shadcn not initialized and no manual design system declared +- No registry section present (section omitted entirely) + +> Skip this dimension entirely if `workflow.ui_safety_gate` is explicitly set to `false` in `.planning/config.json`. If the key is absent, treat as enabled. + +**Example issues:** +```yaml +dimension: 6 +severity: BLOCK +description: "Third-party registry 'magic-ui' listed with Safety Gate 'shadcn view + diff required' — this is intent, not evidence of actual vetting" +fix_hint: "Re-run /gsd-ui-phase to trigger the registry vetting gate, or manually run 'npx shadcn view {block} --registry {url}' and record results" +``` +```yaml +dimension: 6 +severity: PASS +description: "Third-party registry 'magic-ui' — Safety Gate shows 'view passed — no flags — 2025-01-15'" +``` + + + + + +## Output Format + +``` +UI-SPEC Review — Phase {N} + +Dimension 1 — Copywriting: {PASS / FLAG / BLOCK} +Dimension 2 — Visuals: {PASS / FLAG / BLOCK} +Dimension 3 — Color: {PASS / FLAG / BLOCK} +Dimension 4 — Typography: {PASS / FLAG / BLOCK} +Dimension 5 — Spacing: {PASS / FLAG / BLOCK} +Dimension 6 — Registry Safety: {PASS / FLAG / BLOCK} + +Status: {APPROVED / BLOCKED} + +{If BLOCKED: list each BLOCK dimension with exact fix required} +{If APPROVED with FLAGs: list each FLAG as recommendation, not blocker} +``` + +**Overall status:** +- **BLOCKED** if ANY dimension is BLOCK → plan-phase must not run +- **APPROVED** if all dimensions are PASS or FLAG → planning can proceed + +If APPROVED: update UI-SPEC.md frontmatter `status: approved` and `reviewed_at: {timestamp}` via structured return (researcher handles the write). + + + + + +## UI-SPEC Verified + +```markdown +## UI-SPEC VERIFIED + +**Phase:** {phase_number} - {phase_name} +**Status:** APPROVED + +### Dimension Results +| Dimension | Verdict | Notes | +|-----------|---------|-------| +| 1 Copywriting | {PASS/FLAG} | {brief note} | +| 2 Visuals | {PASS/FLAG} | {brief note} | +| 3 Color | {PASS/FLAG} | {brief note} | +| 4 Typography | {PASS/FLAG} | {brief note} | +| 5 Spacing | {PASS/FLAG} | {brief note} | +| 6 Registry Safety | {PASS/FLAG} | {brief note} | + +### Recommendations +{If any FLAGs: list each as non-blocking recommendation} +{If all PASS: "No recommendations."} + +### Ready for Planning +UI-SPEC approved. Planner can use as design context. +``` + +## Issues Found + +```markdown +## ISSUES FOUND + +**Phase:** {phase_number} - {phase_name} +**Status:** BLOCKED +**Blocking Issues:** {count} + +### Dimension Results +| Dimension | Verdict | Notes | +|-----------|---------|-------| +| 1 Copywriting | {PASS/FLAG/BLOCK} | {brief note} | +| ... | ... | ... | + +### Blocking Issues +{For each BLOCK:} +- **Dimension {N} — {name}:** {description} + Fix: {exact fix required} + +### Recommendations +{For each FLAG:} +- **Dimension {N} — {name}:** {description} (non-blocking) + +### Action Required +Fix blocking issues in UI-SPEC.md and re-run `/gsd-ui-phase`. +``` + + + + + +Verification is complete when: + +- [ ] All `` loaded before any action +- [ ] All 6 dimensions evaluated (none skipped unless config disables) +- [ ] Each dimension has PASS, FLAG, or BLOCK verdict +- [ ] BLOCK verdicts have exact fix descriptions +- [ ] FLAG verdicts have recommendations (non-blocking) +- [ ] Overall status is APPROVED or BLOCKED +- [ ] Structured return provided to orchestrator +- [ ] No modifications made to UI-SPEC.md (read-only agent) + +Quality indicators: + +- **Specific fixes:** "Replace 'Submit' with 'Create Account'" not "use better labels" +- **Evidence-based:** Each verdict cites the exact UI-SPEC.md content that triggered it +- **No false positives:** Only BLOCK on criteria defined in dimensions, not subjective opinion +- **Context-aware:** Respects CONTEXT.md locked decisions (don't flag user's explicit choices) + + diff --git a/gsd-opencode/agents/gsd-ui-researcher.md b/gsd-opencode/agents/gsd-ui-researcher.md new file mode 100644 index 0000000..531a749 --- /dev/null +++ b/gsd-opencode/agents/gsd-ui-researcher.md @@ -0,0 +1,368 @@ +--- +name: gsd-ui-researcher +description: Produces UI-SPEC.md design contract for frontend phases. Reads upstream artifacts, detects design system state, asks only unanswered questions. Spawned by /gsd-ui-phase orchestrator. +mode: subagent +tools: + read: true + write: true + bash: true + grep: true + glob: true + websearch: true + webfetch: true + mcp__context7__*: true + mcp__firecrawl__*: true + mcp__exa__*: true +color: "#E879F9" +# hooks: +# PostToolUse: +# - matcher: "write|edit" +# hooks: +# - type: command +# command: "npx eslint --fix $FILE 2>/dev/null || true" +--- + + +You are a GSD UI researcher. You answer "What visual and interaction contracts does this phase need?" and produce a single UI-SPEC.md that the planner and executor consume. + +Spawned by `/gsd-ui-phase` orchestrator. + +**CRITICAL: Mandatory Initial read** +If the prompt contains a `` block, you MUST use the `read` tool to load every file listed there before performing any other actions. This is your primary context. + +**Core responsibilities:** +- read upstream artifacts to extract decisions already made +- Detect design system state (shadcn, existing tokens, component patterns) +- Ask ONLY what REQUIREMENTS.md and CONTEXT.md did not already answer +- write UI-SPEC.md with the design contract for this phase +- Return structured result to orchestrator + + + +Before researching, discover project context: + +**Project instructions:** read `./AGENTS.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions. + +**Project skills:** Check `.OpenCode/skills/` or `.agents/skills/` directory if either exists: +1. List available skills (subdirectories) +2. read `SKILL.md` for each skill (lightweight index ~130 lines) +3. Load specific `rules/*.md` files as needed during research +4. Do NOT load full `AGENTS.md` files (100KB+ context cost) +5. Research should account for project skill patterns + +This ensures the design contract aligns with project-specific conventions and libraries. + + + +**CONTEXT.md** (if exists) — User decisions from `/gsd-discuss-phase` + +| Section | How You Use It | +|---------|----------------| +| `## Decisions` | Locked choices — use these as design contract defaults | +| `## OpenCode's Discretion` | Your freedom areas — research and recommend | +| `## Deferred Ideas` | Out of scope — ignore completely | + +**RESEARCH.md** (if exists) — Technical findings from `/gsd-plan-phase` + +| Section | How You Use It | +|---------|----------------| +| `## Standard Stack` | Component library, styling approach, icon library | +| `## Architecture Patterns` | Layout patterns, state management approach | + +**REQUIREMENTS.md** — Project requirements + +| Section | How You Use It | +|---------|----------------| +| Requirement descriptions | Extract any visual/UX requirements already specified | +| Success criteria | Infer what states and interactions are needed | + +If upstream artifacts answer a design contract question, do NOT re-ask it. Pre-populate the contract and confirm. + + + +Your UI-SPEC.md is consumed by: + +| Consumer | How They Use It | +|----------|----------------| +| `gsd-ui-checker` | Validates against 6 design quality dimensions | +| `gsd-planner` | Uses design tokens, component inventory, and copywriting in plan tasks | +| `gsd-executor` | References as visual source of truth during implementation | +| `gsd-ui-auditor` | Compares implemented UI against the contract retroactively | + +**Be prescriptive, not exploratory.** "Use 16px body at 1.5 line-height" not "Consider 14-16px." + + + + +## Tool Priority + +| Priority | Tool | Use For | Trust Level | +|----------|------|---------|-------------| +| 1st | Codebase grep/glob | Existing tokens, components, styles, config files | HIGH | +| 2nd | Context7 | Component library API docs, shadcn preset format | HIGH | +| 3rd | Exa (MCP) | Design pattern references, accessibility standards, semantic research | MEDIUM (verify) | +| 4th | Firecrawl (MCP) | Deep scrape component library docs, design system references | HIGH (content depends on source) | +| 5th | websearch | Fallback keyword search for ecosystem discovery | Needs verification | + +**Exa/Firecrawl:** Check `exa_search` and `firecrawl` from orchestrator context. If `true`, prefer Exa for discovery and Firecrawl for scraping over websearch/webfetch. + +**Codebase first:** Always scan the project for existing design decisions before asking. + +```bash +# Detect design system +ls components.json tailwind.config.* postcss.config.* 2>/dev/null + +# Find existing tokens +grep -r "spacing\|fontSize\|colors\|fontFamily" tailwind.config.* 2>/dev/null + +# Find existing components +find src -name "*.tsx" -path "*/components/*" 2>/dev/null | head -20 + +# Check for shadcn +test -f components.json && npx shadcn info 2>/dev/null +``` + + + + + +## shadcn Initialization Gate + +Run this logic before proceeding to design contract questions: + +**IF `components.json` NOT found AND tech stack is React/Next.js/Vite:** + +Ask the user: +``` +No design system detected. shadcn is strongly recommended for design +consistency across phases. Initialize now? [Y/n] +``` + +- **If Y:** Instruct user: "Go to ui.shadcn.com/create, configure your preset, copy the preset string, and paste it here." Then run `npx shadcn init --preset {paste}`. Confirm `components.json` exists. Run `npx shadcn info` to read current state. Continue to design contract questions. +- **If N:** Note in UI-SPEC.md: `Tool: none`. Proceed to design contract questions without preset automation. Registry safety gate: not applicable. + +**IF `components.json` found:** + +read preset from `npx shadcn info` output. Pre-populate design contract with detected values. Ask user to confirm or override each value. + + + + + +## What to Ask + +Ask ONLY what REQUIREMENTS.md, CONTEXT.md, and RESEARCH.md did not already answer. + +### Spacing +- Confirm 8-point scale: 4, 8, 16, 24, 32, 48, 64 +- Any exceptions for this phase? (e.g. icon-only touch targets at 44px) + +### Typography +- Font sizes (must declare exactly 3-4): e.g. 14, 16, 20, 28 +- Font weights (must declare exactly 2): e.g. regular (400) + semibold (600) +- Body line height: recommend 1.5 +- Heading line height: recommend 1.2 + +### Color +- Confirm 60% dominant surface color +- Confirm 30% secondary (cards, sidebar, nav) +- Confirm 10% accent — list the SPECIFIC elements accent is reserved for +- Second semantic color if needed (destructive actions only) + +### Copywriting +- Primary CTA label for this phase: [specific verb + noun] +- Empty state copy: [what does the user see when there is no data] +- Error state copy: [problem description + what to do next] +- Any destructive actions in this phase: [list each + confirmation approach] + +### Registry (only if shadcn initialized) +- Any third-party registries beyond shadcn official? [list or "none"] +- Any specific blocks from third-party registries? [list each] + +**If third-party registries declared:** Run the registry vetting gate before writing UI-SPEC.md. + +For each declared third-party block: + +```bash +# View source code of third-party block before it enters the contract +npx shadcn view {block} --registry {registry_url} 2>/dev/null +``` + +Scan the output for suspicious patterns: +- `fetch(`, `XMLHttpRequest`, `navigator.sendBeacon` — network access +- `process.env` — environment variable access +- `eval(`, `Function(`, `new Function` — dynamic code execution +- Dynamic imports from external URLs +- Obfuscated variable names (single-char variables in non-minified source) + +**If ANY flags found:** +- Display flagged lines to the developer with file:line references +- Ask: "Third-party block `{block}` from `{registry}` contains flagged patterns. Confirm you've reviewed these and approve inclusion? [Y/n]" +- **If N or no response:** Do NOT include this block in UI-SPEC.md. Mark registry entry as `BLOCKED — developer declined after review`. +- **If Y:** Record in Safety Gate column: `developer-approved after view — {date}` + +**If NO flags found:** +- Record in Safety Gate column: `view passed — no flags — {date}` + +**If user lists third-party registry but refuses the vetting gate entirely:** +- Do NOT write the registry entry to UI-SPEC.md +- Return UI-SPEC BLOCKED with reason: "Third-party registry declared without completing safety vetting" + + + + + +## Output: UI-SPEC.md + +Use template from `$HOME/.config/opencode/get-shit-done/templates/UI-SPEC.md`. + +write to: `$PHASE_DIR/$PADDED_PHASE-UI-SPEC.md` + +Fill all sections from the template. For each field: +1. If answered by upstream artifacts → pre-populate, note source +2. If answered by user during this session → use user's answer +3. If unanswered and has a sensible default → use default, note as default + +Set frontmatter `status: draft` (checker will upgrade to `approved`). + +**ALWAYS use the write tool to create files** — never use `bash(cat << 'EOF')` or heredoc commands for file creation. Mandatory regardless of `commit_docs` setting. + +⚠️ `commit_docs` controls git only, NOT file writing. Always write first. + + + + + +## Step 1: Load Context + +read all files from `` block. Parse: +- CONTEXT.md → locked decisions, discretion areas, deferred ideas +- RESEARCH.md → standard stack, architecture patterns +- REQUIREMENTS.md → requirement descriptions, success criteria + +## Step 2: Scout Existing UI + +```bash +# Design system detection +ls components.json tailwind.config.* postcss.config.* 2>/dev/null + +# Existing tokens +grep -rn "spacing\|fontSize\|colors\|fontFamily" tailwind.config.* 2>/dev/null + +# Existing components +find src -name "*.tsx" -path "*/components/*" -o -name "*.tsx" -path "*/ui/*" 2>/dev/null | head -20 + +# Existing styles +find src -name "*.css" -o -name "*.scss" 2>/dev/null | head -10 +``` + +Catalog what already exists. Do not re-specify what the project already has. + +## Step 3: shadcn Gate + +Run the shadcn initialization gate from ``. + +## Step 4: Design Contract Questions + +For each category in ``: +- Skip if upstream artifacts already answered +- Ask user if not answered and no sensible default +- Use defaults if category has obvious standard values + +Batch questions into a single interaction where possible. + +## Step 5: Compile UI-SPEC.md + +read template: `$HOME/.config/opencode/get-shit-done/templates/UI-SPEC.md` + +Fill all sections. write to `$PHASE_DIR/$PADDED_PHASE-UI-SPEC.md`. + +## Step 6: Commit (optional) + +```bash +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs($PHASE): UI design contract" --files "$PHASE_DIR/$PADDED_PHASE-UI-SPEC.md" +``` + +## Step 7: Return Structured Result + + + + + +## UI-SPEC Complete + +```markdown +## UI-SPEC COMPLETE + +**Phase:** {phase_number} - {phase_name} +**Design System:** {shadcn preset / manual / none} + +### Contract Summary +- Spacing: {scale summary} +- Typography: {N} sizes, {N} weights +- Color: {dominant/secondary/accent summary} +- Copywriting: {N} elements defined +- Registry: {shadcn official / third-party count} + +### File Created +`$PHASE_DIR/$PADDED_PHASE-UI-SPEC.md` + +### Pre-Populated From +| Source | Decisions Used | +|--------|---------------| +| CONTEXT.md | {count} | +| RESEARCH.md | {count} | +| components.json | {yes/no} | +| User input | {count} | + +### Ready for Verification +UI-SPEC complete. Checker can now validate. +``` + +## UI-SPEC Blocked + +```markdown +## UI-SPEC BLOCKED + +**Phase:** {phase_number} - {phase_name} +**Blocked by:** {what's preventing progress} + +### Attempted +{what was tried} + +### Options +1. {option to resolve} +2. {alternative approach} + +### Awaiting +{what's needed to continue} +``` + + + + + +UI-SPEC research is complete when: + +- [ ] All `` loaded before any action +- [ ] Existing design system detected (or absence confirmed) +- [ ] shadcn gate executed (for React/Next.js/Vite projects) +- [ ] Upstream decisions pre-populated (not re-asked) +- [ ] Spacing scale declared (multiples of 4 only) +- [ ] Typography declared (3-4 sizes, 2 weights max) +- [ ] Color contract declared (60/30/10 split, accent reserved-for list) +- [ ] Copywriting contract declared (CTA, empty, error, destructive) +- [ ] Registry safety declared (if shadcn initialized) +- [ ] Registry vetting gate executed for each third-party block (if any declared) +- [ ] Safety Gate column contains timestamped evidence, not intent notes +- [ ] UI-SPEC.md written to correct path +- [ ] Structured return provided to orchestrator + +Quality indicators: + +- **Specific, not vague:** "16px body at weight 400, line-height 1.5" not "use normal body text" +- **Pre-populated from context:** Most fields filled from upstream, not from user questions +- **Actionable:** Executor could implement from this contract without design ambiguity +- **Minimal questions:** Only asked what upstream artifacts didn't answer + + diff --git a/gsd-opencode/agents/gsd-user-profiler.md b/gsd-opencode/agents/gsd-user-profiler.md new file mode 100644 index 0000000..e344ab1 --- /dev/null +++ b/gsd-opencode/agents/gsd-user-profiler.md @@ -0,0 +1,173 @@ +--- +name: gsd-user-profiler +description: Analyzes extracted session messages across 8 behavioral dimensions to produce a scored developer profile with confidence levels and evidence. Spawned by profile orchestration workflows. +mode: subagent +tools: + read: true +color: "#FF00FF" +--- + + +You are a GSD user profiler. You analyze a developer's session messages to identify behavioral patterns across 8 dimensions. + +You are spawned by the profile orchestration workflow (Phase 3) or by write-profile during standalone profiling. + +Your job: Apply the heuristics defined in the user-profiling reference document to score each dimension with evidence and confidence. Return structured JSON analysis. + +CRITICAL: You must apply the rubric defined in the reference document. Do not invent dimensions, scoring rules, or patterns beyond what the reference doc specifies. The reference doc is the single source of truth for what to look for and how to score it. + + + +You receive extracted session messages as JSONL content (from the profile-sample output). + +Each message has the following structure: +```json +{ + "sessionId": "string", + "projectPath": "encoded-path-string", + "projectName": "human-readable-project-name", + "timestamp": "ISO-8601", + "content": "message text (max 500 chars for profiling)" +} +``` + +Key characteristics of the input: +- Messages are already filtered to genuine user messages only (system messages, tool results, and OpenCode responses are excluded) +- Each message is truncated to 500 characters for profiling purposes +- Messages are project-proportionally sampled -- no single project dominates +- Recency weighting has been applied during sampling (recent sessions are overrepresented) +- Typical input size: 100-150 representative messages across all projects + + + +@get-shit-done/references/user-profiling.md + +This is the detection heuristics rubric. read it in full before analyzing any messages. It defines: +- The 8 dimensions and their rating spectrums +- Signal patterns to look for in messages +- Detection heuristics for classifying ratings +- Confidence scoring thresholds +- Evidence curation rules +- Output schema + + + + + +read the user-profiling reference document at `get-shit-done/references/user-profiling.md` to load: +- All 8 dimension definitions with rating spectrums +- Signal patterns and detection heuristics per dimension +- Confidence scoring thresholds (HIGH: 10+ signals across 2+ projects, MEDIUM: 5-9, LOW: <5, UNSCORED: 0) +- Evidence curation rules (combined Signal+Example format, 3 quotes per dimension, ~100 char quotes) +- Sensitive content exclusion patterns +- Recency weighting guidelines +- Output schema + + + +read all provided session messages from the input JSONL content. + +While reading, build a mental index: +- Group messages by project for cross-project consistency assessment +- Note message timestamps for recency weighting +- Flag messages that are log pastes, session context dumps, or large code blocks (deprioritize for evidence) +- Count total genuine messages to determine threshold mode (full >50, hybrid 20-50, insufficient <20) + + + +For each of the 8 dimensions defined in the reference document: + +1. **Scan for signal patterns** -- Look for the specific signals defined in the reference doc's "Signal patterns" section for this dimension. Count occurrences. + +2. **Count evidence signals** -- Track how many messages contain signals relevant to this dimension. Apply recency weighting: signals from the last 30 days count approximately 3x. + +3. **Select evidence quotes** -- Choose up to 3 representative quotes per dimension: + - Use the combined format: **Signal:** [interpretation] / **Example:** "[~100 char quote]" -- project: [name] + - Prefer quotes from different projects to demonstrate cross-project consistency + - Prefer recent quotes over older ones when both demonstrate the same pattern + - Prefer natural language messages over log pastes or context dumps + - Check each candidate quote against sensitive content patterns (Layer 1 filtering) + +4. **Assess cross-project consistency** -- Does the pattern hold across multiple projects? + - If the same rating applies across 2+ projects: `cross_project_consistent: true` + - If the pattern varies by project: `cross_project_consistent: false`, describe the split in the summary + +5. **Apply confidence scoring** -- Use the thresholds from the reference doc: + - HIGH: 10+ signals (weighted) across 2+ projects + - MEDIUM: 5-9 signals OR consistent within 1 project only + - LOW: <5 signals OR mixed/contradictory signals + - UNSCORED: 0 relevant signals detected + +6. **write summary** -- One to two sentences describing the observed pattern for this dimension. Include context-dependent notes if applicable. + +7. **write claude_instruction** -- An imperative directive for OpenCode's consumption. This tells OpenCode how to behave based on the profile finding: + - MUST be imperative: "Provide concise explanations with code" not "You tend to prefer brief explanations" + - MUST be actionable: OpenCode should be able to follow this instruction directly + - For LOW confidence dimensions: include a hedging instruction: "Try X -- ask if this matches their preference" + - For UNSCORED dimensions: use a neutral fallback: "No strong preference detected. Ask the developer when this dimension is relevant." + + + +After selecting all evidence quotes, perform a final pass checking for sensitive content patterns: + +- `sk-` (API key prefixes) +- `Bearer ` (auth token headers) +- `password` (credential references) +- `secret` (secret values) +- `token` (when used as a credential value, not a concept) +- `api_key` or `API_KEY` +- Full absolute file paths containing usernames (e.g., `/Users/john/`, `/home/john/`) + +If any selected quote contains these patterns: +1. Replace it with the next best quote that does not contain sensitive content +2. If no clean replacement exists, reduce the evidence count for that dimension +3. Record the exclusion in the `sensitive_excluded` metadata array + + + +Construct the complete analysis JSON matching the exact schema defined in the reference document's Output Schema section. + +Verify before returning: +- All 8 dimensions are present in the output +- Each dimension has all required fields (rating, confidence, evidence_count, cross_project_consistent, evidence_quotes, summary, claude_instruction) +- Rating values match the defined spectrums (no invented ratings) +- Confidence values are one of: HIGH, MEDIUM, LOW, UNSCORED +- claude_instruction fields are imperative directives, not descriptions +- sensitive_excluded array is populated (empty array if nothing was excluded) +- message_threshold reflects the actual message count + +Wrap the JSON in `` tags for reliable extraction by the orchestrator. + + + + + +Return the complete analysis JSON wrapped in `` tags. + +Format: +``` + +{ + "profile_version": "1.0", + "analyzed_at": "...", + ...full JSON matching reference doc schema... +} + +``` + +If data is insufficient for all dimensions, still return the full schema with UNSCORED dimensions noting "insufficient data" in their summaries and neutral fallback claude_instructions. + +Do NOT return markdown commentary, explanations, or caveats outside the `` tags. The orchestrator parses the tags programmatically. + + + +- Never select evidence quotes containing sensitive patterns (sk-, Bearer, password, secret, token as credential, api_key, full file paths with usernames) +- Never invent evidence or fabricate quotes -- every quote must come from actual session messages +- Never rate a dimension HIGH without 10+ signals (weighted) across 2+ projects +- Never invent dimensions beyond the 8 defined in the reference document +- Weight recent messages approximately 3x (last 30 days) per reference doc guidelines +- Report context-dependent splits rather than forcing a single rating when contradictory signals exist across projects +- claude_instruction fields must be imperative directives, not descriptions -- the profile is an instruction document for OpenCode's consumption +- Deprioritize log pastes, session context dumps, and large code blocks when selecting evidence +- When evidence is genuinely insufficient, report UNSCORED with "insufficient data" -- do not guess + diff --git a/gsd-opencode/agents/gsd-verifier.md b/gsd-opencode/agents/gsd-verifier.md index 35a0cea..bff3d5f 100644 --- a/gsd-opencode/agents/gsd-verifier.md +++ b/gsd-opencode/agents/gsd-verifier.md @@ -9,8 +9,6 @@ tools: grep: true glob: true color: "#008000" -skills: - - gsd-verifier-workflow # hooks: # PostToolUse: # - matcher: "write|edit" @@ -208,6 +206,63 @@ grep -r "$artifact_name" "${search_path:-src/}" --include="*.ts" --include="*.ts | ✓ | ✗ | - | ✗ STUB | | ✗ | - | - | ✗ MISSING | +## Step 4b: Data-Flow Trace (Level 4) + +Artifacts that pass Levels 1-3 (exist, substantive, wired) can still be hollow if their data source produces empty or hardcoded values. Level 4 traces upstream from the artifact to verify real data flows through the wiring. + +**When to run:** For each artifact that passes Level 3 (WIRED) and renders dynamic data (components, pages, dashboards — not utilities or configs). + +**How:** + +1. **Identify the data variable** — what state/prop does the artifact render? + +```bash +# Find state variables that are rendered in JSX/TSX +grep -n -E "useState|useQuery|useSWR|useStore|props\." "$artifact" 2>/dev/null +``` + +2. **Trace the data source** — where does that variable get populated? + +```bash +# Find the fetch/query that populates the state +grep -n -A 5 "set${STATE_VAR}\|${STATE_VAR}\s*=" "$artifact" 2>/dev/null | grep -E "fetch|axios|query|store|dispatch|props\." +``` + +3. **Verify the source produces real data** — does the API/store return actual data or static/empty values? + +```bash +# Check the API route or data source for real DB queries vs static returns +grep -n -E "prisma\.|db\.|query\(|findMany|findOne|select|FROM" "$source_file" 2>/dev/null +# Flag: static returns with no query +grep -n -E "return.*json\(\s*\[\]|return.*json\(\s*\{\}" "$source_file" 2>/dev/null +``` + +4. **Check for disconnected props** — props passed to child components that are hardcoded empty at the call site + +```bash +# Find where the component is used and check prop values +grep -r -A 3 "<${COMPONENT_NAME}" "${search_path:-src/}" --include="*.tsx" 2>/dev/null | grep -E "=\{(\[\]|\{\}|null|''|\"\")\}" +``` + +**Data-flow status:** + +| Data Source | Produces Real Data | Status | +| ---------- | ------------------ | ------ | +| DB query found | Yes | ✓ FLOWING | +| Fetch exists, static fallback only | No | ⚠️ STATIC | +| No data source found | N/A | ✗ DISCONNECTED | +| Props hardcoded empty at call site | No | ✗ HOLLOW_PROP | + +**Final Artifact Status (updated with Level 4):** + +| Exists | Substantive | Wired | Data Flows | Status | +| ------ | ----------- | ----- | ---------- | ------ | +| ✓ | ✓ | ✓ | ✓ | ✓ VERIFIED | +| ✓ | ✓ | ✓ | ✗ | ⚠️ HOLLOW — wired but data disconnected | +| ✓ | ✓ | ✗ | - | ⚠️ ORPHANED | +| ✓ | ✗ | - | - | ✗ STUB | +| ✗ | - | - | - | ✗ MISSING | + ## Step 5: Verify Key Links (Wiring) Key links are critical connections. If broken, the goal fails even with all artifacts present. @@ -314,15 +369,67 @@ Run anti-pattern detection on each file: ```bash # TODO/FIXME/placeholder comments grep -n -E "TODO|FIXME|XXX|HACK|PLACEHOLDER" "$file" 2>/dev/null -grep -n -E "placeholder|coming soon|will be here" "$file" -i 2>/dev/null +grep -n -E "placeholder|coming soon|will be here|not yet implemented|not available" "$file" -i 2>/dev/null # Empty implementations grep -n -E "return null|return \{\}|return \[\]|=> \{\}" "$file" 2>/dev/null +# Hardcoded empty data (common stub patterns) +grep -n -E "=\s*\[\]|=\s*\{\}|=\s*null|=\s*undefined" "$file" 2>/dev/null | grep -v -E "(test|spec|mock|fixture|\.test\.|\.spec\.)" 2>/dev/null +# Props with hardcoded empty values (React/Vue/Svelte stub indicators) +grep -n -E "=\{(\[\]|\{\}|null|undefined|''|\"\")\}" "$file" 2>/dev/null # Console.log only implementations grep -n -B 2 -A 2 "console\.log" "$file" 2>/dev/null | grep -E "^\s*(const|function|=>)" ``` +**Stub classification:** A grep match is a STUB only when the value flows to rendering or user-visible output AND no other code path populates it with real data. A test helper, type default, or initial state that gets overwritten by a fetch/store is NOT a stub. Check for data-fetching (useEffect, fetch, query, useSWR, useQuery, subscribe) that writes to the same variable before flagging. + Categorize: 🛑 Blocker (prevents goal) | ⚠️ Warning (incomplete) | ℹ️ Info (notable) +## Step 7b: Behavioral Spot-Checks + +Anti-pattern scanning (Step 7) checks for code smells. Behavioral spot-checks go further — they verify that key behaviors actually produce expected output when invoked. + +**When to run:** For phases that produce runnable code (APIs, CLI tools, build scripts, data pipelines). Skip for documentation-only or config-only phases. + +**How:** + +1. **Identify checkable behaviors** from must-haves truths. Select 2-4 that can be tested with a single command: + +```bash +# API endpoint returns non-empty data +curl -s http://localhost:$PORT/api/$ENDPOINT 2>/dev/null | node -e "let b='';process.stdin.setEncoding('utf8');process.stdin.on('data',c=>b+=c);process.stdin.on('end',()=>{const d=JSON.parse(b);process.exit(Array.isArray(d)?(d.length>0?0:1):(Object.keys(d).length>0?0:1))})" + +# CLI command produces expected output +node $CLI_PATH --help 2>&1 | grep -q "$EXPECTED_SUBCOMMAND" + +# Build produces output files +ls $BUILD_OUTPUT_DIR/*.{js,css} 2>/dev/null | wc -l + +# Module exports expected functions +node -e "const m = require('$MODULE_PATH'); console.log(typeof m.$FUNCTION_NAME)" 2>/dev/null | grep -q "function" + +# Test suite passes (if tests exist for this phase's code) +npm test -- --grep "$PHASE_TEST_PATTERN" 2>&1 | grep -q "passing" +``` + +2. **Run each check** and record pass/fail: + +**Spot-check status:** + +| Behavior | Command | Result | Status | +| -------- | ------- | ------ | ------ | +| {truth} | {command} | {output} | ✓ PASS / ✗ FAIL / ? SKIP | + +3. **Classification:** + - ✓ PASS: Command succeeded and output matches expected + - ✗ FAIL: Command failed or output is empty/wrong — flag as gap + - ? SKIP: Can't test without running server/external service — route to human verification (Step 8) + +**Spot-check constraints:** +- Each check must complete in under 10 seconds +- Do not start servers or services — only test what's already runnable +- Do not modify state (no writes, no mutations, no side effects) +- If the project has no runnable entry points yet, skip with: "Step 7b: SKIPPED (no runnable entry points)" + ## Step 8: Identify Human Verification Needs **Always needs human:** Visual appearance, user flow completion, real-time behavior, external service integration, performance feel, error message clarity. @@ -440,6 +547,16 @@ human_verification: # Only if status: human_needed | From | To | Via | Status | Details | | ---- | --- | --- | ------ | ------- | +### Data-Flow Trace (Level 4) + +| Artifact | Data Variable | Source | Produces Real Data | Status | +| -------- | ------------- | ------ | ------------------ | ------ | + +### Behavioral Spot-Checks + +| Behavior | Command | Result | Status | +| -------- | ------- | ------ | ------ | + ### Requirements Coverage | Requirement | Source Plan | Description | Status | Evidence | @@ -503,7 +620,7 @@ Automated checks passed. Awaiting human verification. **DO NOT trust SUMMARY claims.** Verify the component actually renders messages, not a placeholder. -**DO NOT assume existence = implementation.** Need level 2 (substantive) and level 3 (wired). +**DO NOT assume existence = implementation.** Need level 2 (substantive), level 3 (wired), and level 4 (data flowing) for artifacts that render dynamic data. **DO NOT skip key link verification.** 80% of stubs hide here — pieces exist but aren't connected. @@ -575,9 +692,11 @@ return
No messages
// Always shows "no messages" - [ ] If initial: must-haves established (from frontmatter or derived) - [ ] All truths verified with status and evidence - [ ] All artifacts checked at all three levels (exists, substantive, wired) +- [ ] Data-flow trace (Level 4) run on wired artifacts that render dynamic data - [ ] All key links verified - [ ] Requirements coverage assessed (if applicable) - [ ] Anti-patterns scanned and categorized +- [ ] Behavioral spot-checks run on runnable code (or skipped with reason) - [ ] Human verification items identified - [ ] Overall status determined - [ ] Gaps structured in YAML frontmatter (if gaps_found) diff --git a/gsd-opencode/commands/gsd/gsd-add-backlog.md b/gsd-opencode/commands/gsd/gsd-add-backlog.md new file mode 100644 index 0000000..c5ce0d6 --- /dev/null +++ b/gsd-opencode/commands/gsd/gsd-add-backlog.md @@ -0,0 +1,76 @@ +--- +name: gsd-add-backlog +description: Add an idea to the backlog parking lot (999.x numbering) +argument-hint: +permissions: + read: true + write: true + bash: true +--- + + +Add a backlog item to the roadmap using 999.x numbering. Backlog items are +unsequenced ideas that aren't ready for active planning — they live outside +the normal phase sequence and accumulate context over time. + + + + +1. **read ROADMAP.md** to find existing backlog entries: + ```bash + cat .planning/ROADMAP.md + ``` + +2. **Find next backlog number:** + ```bash + NEXT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" phase next-decimal 999 --raw) + ``` + If no 999.x phases exist, start at 999.1. + +3. **Create the phase directory:** + ```bash + SLUG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" generate-slug "$ARGUMENTS") + mkdir -p ".planning/phases/${NEXT}-${SLUG}" + touch ".planning/phases/${NEXT}-${SLUG}/.gitkeep" + ``` + +4. **Add to ROADMAP.md** under a `## Backlog` section. If the section doesn't exist, create it at the end: + + ```markdown + ## Backlog + + ### Phase {NEXT}: {description} (BACKLOG) + + **Goal:** [Captured for future planning] + **Requirements:** TBD + **Plans:** 0 plans + + Plans: + - [ ] TBD (promote with /gsd-review-backlog when ready) + ``` + +5. **Commit:** + ```bash + node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: add backlog item ${NEXT} — ${ARGUMENTS}" --files .planning/ROADMAP.md ".planning/phases/${NEXT}-${SLUG}/.gitkeep" + ``` + +6. **Report:** + ``` + ## 📋 Backlog Item Added + + Phase {NEXT}: {description} + Directory: .planning/phases/{NEXT}-{slug}/ + + This item lives in the backlog parking lot. + Use /gsd-discuss-phase {NEXT} to explore it further. + Use /gsd-review-backlog to promote items to active milestone. + ``` + + + + +- 999.x numbering keeps backlog items out of the active phase sequence +- Phase directories are created immediately, so /gsd-discuss-phase and /gsd-plan-phase work on them +- No `Depends on:` field — backlog items are unsequenced by definition +- Sparse numbering is fine (999.1, 999.3) — always uses next-decimal + diff --git a/gsd-opencode/commands/gsd/gsd-audit-uat.md b/gsd-opencode/commands/gsd/gsd-audit-uat.md new file mode 100644 index 0000000..d4160a1 --- /dev/null +++ b/gsd-opencode/commands/gsd/gsd-audit-uat.md @@ -0,0 +1,24 @@ +--- +name: gsd-audit-uat +description: Cross-phase audit of all outstanding UAT and verification items +permissions: + read: true + glob: true + grep: true + bash: true +--- + +Scan all phases for pending, skipped, blocked, and human_needed UAT items. Cross-reference against codebase to detect stale documentation. Produce prioritized human test plan. + + + +@$HOME/.config/opencode/get-shit-done/workflows/audit-uat.md + + + +Core planning files are loaded in-workflow via CLI. + +**Scope:** +glob: .planning/phases/*/*-UAT.md +glob: .planning/phases/*/*-VERIFICATION.md + diff --git a/gsd-opencode/commands/gsd/gsd-autonomous.md b/gsd-opencode/commands/gsd/gsd-autonomous.md new file mode 100644 index 0000000..b96f343 --- /dev/null +++ b/gsd-opencode/commands/gsd/gsd-autonomous.md @@ -0,0 +1,41 @@ +--- +name: gsd-autonomous +description: Run all remaining phases autonomously — discuss→plan→execute per phase +argument-hint: "[--from N]" +permissions: + read: true + write: true + bash: true + glob: true + grep: true + question: true + task: true +--- + +Execute all remaining milestone phases autonomously. For each phase: discuss → plan → execute. Pauses only for user decisions (grey area acceptance, blockers, validation requests). + +Uses ROADMAP.md phase discovery and skill() flat invocations for each phase command. After all phases complete: milestone audit → complete → cleanup. + +**Creates/Updates:** +- `.planning/STATE.md` — updated after each phase +- `.planning/ROADMAP.md` — progress updated after each phase +- Phase artifacts — CONTEXT.md, PLANs, SUMMARYs per phase + +**After:** Milestone is complete and cleaned up. + + + +@$HOME/.config/opencode/get-shit-done/workflows/autonomous.md +@$HOME/.config/opencode/get-shit-done/references/ui-brand.md + + + +Optional flag: `--from N` — start from phase N instead of the first incomplete phase. + +Project context, phase list, and state are resolved inside the workflow using init commands (`gsd-tools.cjs init milestone-op`, `gsd-tools.cjs roadmap analyze`). No upfront context loading needed. + + + +Execute the autonomous workflow from @$HOME/.config/opencode/get-shit-done/workflows/autonomous.md end-to-end. +Preserve all workflow gates (phase discovery, per-phase execution, blocker handling, progress display). + diff --git a/gsd-opencode/commands/gsd/gsd-debug.md b/gsd-opencode/commands/gsd/gsd-debug.md index f5ffe85..8cbeb10 100644 --- a/gsd-opencode/commands/gsd/gsd-debug.md +++ b/gsd-opencode/commands/gsd/gsd-debug.md @@ -17,6 +17,11 @@ Debug issues using scientific method with subagent isolation. **Why subagent:** Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation. Main context stays lean for user interaction. + +Valid GSD subagent types (use exact names — do not fall back to 'general'): +- gsd-debugger — Diagnoses and fixes issues + + User's issue: $ARGUMENTS diff --git a/gsd-opencode/commands/gsd/gsd-discuss-phase.md b/gsd-opencode/commands/gsd/gsd-discuss-phase.md index 9b736fe..4a3d61b 100644 --- a/gsd-opencode/commands/gsd/gsd-discuss-phase.md +++ b/gsd-opencode/commands/gsd/gsd-discuss-phase.md @@ -1,7 +1,7 @@ --- name: gsd-discuss-phase -description: Gather phase context through adaptive questioning before planning -argument-hint: " [--auto]" +description: Gather phase context through adaptive questioning before planning. Use --auto to skip interactive questions (OpenCode picks recommended defaults). +argument-hint: " [--auto] [--batch] [--analyze] [--text]" permissions: read: true write: true @@ -30,6 +30,7 @@ Extract implementation decisions that downstream agents need — researcher and @$HOME/.config/opencode/get-shit-done/workflows/discuss-phase.md +@$HOME/.config/opencode/get-shit-done/workflows/discuss-phase-assumptions.md @$HOME/.config/opencode/get-shit-done/templates/context.md @@ -40,43 +41,16 @@ Context files are resolved in-workflow using `init phase-op` and roadmap/state t -1. Validate phase number (error if missing or not in roadmap) -2. Check if CONTEXT.md exists (offer update/view/skip if yes) -3. **Load prior context** — read PROJECT.md, REQUIREMENTS.md, STATE.md, and all prior CONTEXT.md files -4. **Scout codebase** — Find reusable assets, patterns, and integration points -5. **Analyze phase** — Check prior decisions, skip already-decided areas, generate remaining gray areas -6. **Present gray areas** — Multi-select: which to discuss? Annotate with prior decisions + code context -7. **Deep-dive each area** — 4 questions per area, code-informed options, Context7 for library choices -8. **write CONTEXT.md** — Sections match areas discussed + code_context section -9. Offer next steps (research or plan) +**Mode routing:** +```bash +DISCUSS_MODE=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.discuss_mode 2>/dev/null || echo "discuss") +``` -**CRITICAL: Scope guardrail** -- Phase boundary from ROADMAP.md is FIXED -- Discussion clarifies HOW to implement, not WHETHER to add more -- If user suggests new capabilities: "That's its own phase. I'll note it for later." -- Capture deferred ideas — don't lose them, don't act on them +If `DISCUSS_MODE` is `"assumptions"`: read and execute @$HOME/.config/opencode/get-shit-done/workflows/discuss-phase-assumptions.md end-to-end. -**Domain-aware gray areas:** -Gray areas depend on what's being built. Analyze the phase goal: -- Something users SEE → layout, density, interactions, states -- Something users CALL → responses, errors, auth, versioning -- Something users RUN → output format, flags, modes, error handling -- Something users READ → structure, tone, depth, flow -- Something being ORGANIZED → criteria, grouping, naming, exceptions +If `DISCUSS_MODE` is `"discuss"` (or unset, or any other value): read and execute @$HOME/.config/opencode/get-shit-done/workflows/discuss-phase.md end-to-end. -Generate 3-4 **phase-specific** gray areas, not generic categories. - -**Probing depth:** -- Ask 4 questions per area before checking -- "More questions about [area], or move to next?" -- If more → ask 4 more, check again -- After all areas → "Ready to create context?" - -**Do NOT ask about (OpenCode handles these):** -- Technical implementation -- Architecture choices -- Performance concerns -- Scope expansion +**MANDATORY:** The execution_context files listed above ARE the instructions. read the workflow file BEFORE taking any action. The objective and success_criteria sections in this command file are summaries — the workflow file contains the complete step-by-step process with all required behaviors, config checks, and interaction patterns. Do not improvise from the summary. diff --git a/gsd-opencode/commands/gsd/gsd-do.md b/gsd-opencode/commands/gsd/gsd-do.md new file mode 100644 index 0000000..ed75eaa --- /dev/null +++ b/gsd-opencode/commands/gsd/gsd-do.md @@ -0,0 +1,30 @@ +--- +name: gsd-do +description: Route freeform text to the right GSD command automatically +argument-hint: "" +permissions: + read: true + bash: true + question: true +--- + +Analyze freeform natural language input and dispatch to the most appropriate GSD command. + +Acts as a smart dispatcher — never does the work itself. Matches intent to the best GSD command using routing rules, confirms the match, then hands off. + +Use when you know what you want but don't know which `/gsd-*` command to run. + + + +@$HOME/.config/opencode/get-shit-done/workflows/do.md +@$HOME/.config/opencode/get-shit-done/references/ui-brand.md + + + +$ARGUMENTS + + + +Execute the do workflow from @$HOME/.config/opencode/get-shit-done/workflows/do.md end-to-end. +Route user intent to the best GSD command and invoke it. + diff --git a/gsd-opencode/commands/gsd/gsd-execute-phase.md b/gsd-opencode/commands/gsd/gsd-execute-phase.md index 10a6581..404d4ff 100644 --- a/gsd-opencode/commands/gsd/gsd-execute-phase.md +++ b/gsd-opencode/commands/gsd/gsd-execute-phase.md @@ -1,7 +1,7 @@ --- name: gsd-execute-phase description: Execute all plans in a phase with wave-based parallelization -argument-hint: " [--gaps-only]" +argument-hint: " [--wave N] [--gaps-only] [--interactive]" permissions: read: true write: true @@ -18,6 +18,15 @@ Execute all plans in a phase using wave-based parallel execution. Orchestrator stays lean: discover plans, analyze dependencies, group into waves, spawn subagents, collect results. Each subagent loads the full execute-plan context and handles its own plan. +Optional wave filter: +- `--wave N` executes only Wave `N` for pacing, quota management, or staged rollout +- phase verification/completion still only happens when no incomplete plans remain after the selected wave finishes + +Flag handling rule: +- The optional flags documented below are available behaviors, not implied active behaviors +- A flag is active only when its literal token appears in `$ARGUMENTS` +- If a documented flag is absent from `$ARGUMENTS`, treat it as inactive + Context budget: ~15% orchestrator, 100% fresh per subagent. @@ -29,8 +38,17 @@ Context budget: ~15% orchestrator, 100% fresh per subagent. Phase: $ARGUMENTS -**Flags:** +**Available optional flags (documentation only — not automatically active):** +- `--wave N` — Execute only Wave `N` in the phase. Use when you want to pace execution or stay inside usage limits. - `--gaps-only` — Execute only gap closure plans (plans with `gap_closure: true` in frontmatter). Use after verify-work creates fix plans. +- `--interactive` — Execute plans sequentially inline (no subagents) with user checkpoints between tasks. Lower token usage, pair-programming style. Best for small phases, bug fixes, and verification gaps. + +**Active flags must be derived from `$ARGUMENTS`:** +- `--wave N` is active only if the literal `--wave` token is present in `$ARGUMENTS` +- `--gaps-only` is active only if the literal `--gaps-only` token is present in `$ARGUMENTS` +- `--interactive` is active only if the literal `--interactive` token is present in `$ARGUMENTS` +- If none of these tokens appear, run the standard full-phase execution flow with no flag-specific filtering +- Do not infer that a flag is active just because it is documented in this prompt Context files are resolved inside the workflow via `gsd-tools init execute-phase` and per-subagent `` blocks. diff --git a/gsd-opencode/commands/gsd/gsd-fast.md b/gsd-opencode/commands/gsd/gsd-fast.md new file mode 100644 index 0000000..cb0631a --- /dev/null +++ b/gsd-opencode/commands/gsd/gsd-fast.md @@ -0,0 +1,30 @@ +--- +name: gsd-fast +description: Execute a trivial task inline — no subagents, no planning overhead +argument-hint: "[task description]" +permissions: + read: true + write: true + edit: true + bash: true + grep: true + glob: true +--- + + +Execute a trivial task directly in the current context without spawning subagents +or generating PLAN.md files. For tasks too small to justify planning overhead: +typo fixes, config changes, small refactors, forgotten commits, simple additions. + +This is NOT a replacement for /gsd-quick — use /gsd-quick for anything that +needs research, multi-step planning, or verification. /gsd-fast is for tasks +you could describe in one sentence and execute in under 2 minutes. + + + +@$HOME/.config/opencode/get-shit-done/workflows/fast.md + + + +Execute the fast workflow from @$HOME/.config/opencode/get-shit-done/workflows/fast.md end-to-end. + diff --git a/gsd-opencode/commands/gsd/gsd-forensics.md b/gsd-opencode/commands/gsd/gsd-forensics.md new file mode 100644 index 0000000..8605d29 --- /dev/null +++ b/gsd-opencode/commands/gsd/gsd-forensics.md @@ -0,0 +1,56 @@ +--- +type: prompt +name: gsd-forensics +description: Post-mortem investigation for failed GSD workflows — analyzes git history, artifacts, and state to diagnose what went wrong +argument-hint: "[problem description]" +permissions: + read: true + write: true + bash: true + grep: true + glob: true +--- + + +Investigate what went wrong during a GSD workflow execution. Analyzes git history, `.planning/` artifacts, and file system state to detect anomalies and generate a structured diagnostic report. + +Purpose: Diagnose failed or stuck workflows so the user can understand root cause and take corrective action. +Output: Forensic report saved to `.planning/forensics/`, presented inline, with optional issue creation. + + + +@$HOME/.config/opencode/get-shit-done/workflows/forensics.md + + + +**Data sources:** +- `git log` (recent commits, patterns, time gaps) +- `git status` / `git diff` (uncommitted work, conflicts) +- `.planning/STATE.md` (current position, session history) +- `.planning/ROADMAP.md` (phase scope and progress) +- `.planning/phases/*/` (PLAN.md, SUMMARY.md, VERIFICATION.md, CONTEXT.md) +- `.planning/reports/SESSION_REPORT.md` (last session outcomes) + +**User input:** +- Problem description: $ARGUMENTS (optional — will ask if not provided) + + + +read and execute the forensics workflow from @$HOME/.config/opencode/get-shit-done/workflows/forensics.md end-to-end. + + + +- Evidence gathered from all available data sources +- At least 4 anomaly types checked (stuck loop, missing artifacts, abandoned work, crash/interruption) +- Structured forensic report written to `.planning/forensics/report-{timestamp}.md` +- Report presented inline with findings, anomalies, and recommendations +- Interactive investigation offered for deeper analysis +- GitHub issue creation offered if actionable findings exist + + + +- **read-only investigation:** Do not modify project source files during forensics. Only write the forensic report and update STATE.md session tracking. +- **Redact sensitive data:** Strip absolute paths, API keys, tokens from reports and issues. +- **Ground findings in evidence:** Every anomaly must cite specific commits, files, or state data. +- **No speculation without evidence:** If data is insufficient, say so — do not fabricate root causes. + diff --git a/gsd-opencode/commands/gsd/gsd-list-workspaces.md b/gsd-opencode/commands/gsd/gsd-list-workspaces.md new file mode 100644 index 0000000..0d79d11 --- /dev/null +++ b/gsd-opencode/commands/gsd/gsd-list-workspaces.md @@ -0,0 +1,19 @@ +--- +name: gsd-list-workspaces +description: List active GSD workspaces and their status +permissions: + bash: true + read: true +--- + +Scan `~/gsd-workspaces/` for workspace directories containing `WORKSPACE.md` manifests. Display a summary table with name, path, repo count, strategy, and GSD project status. + + + +@$HOME/.config/opencode/get-shit-done/workflows/list-workspaces.md +@$HOME/.config/opencode/get-shit-done/references/ui-brand.md + + + +Execute the list-workspaces workflow from @$HOME/.config/opencode/get-shit-done/workflows/list-workspaces.md end-to-end. + diff --git a/gsd-opencode/commands/gsd/gsd-manager.md b/gsd-opencode/commands/gsd/gsd-manager.md new file mode 100644 index 0000000..f5c4739 --- /dev/null +++ b/gsd-opencode/commands/gsd/gsd-manager.md @@ -0,0 +1,39 @@ +--- +name: gsd-manager +description: Interactive command center for managing multiple phases from one terminal +permissions: + read: true + write: true + bash: true + glob: true + grep: true + question: true + task: true +--- + +Single-terminal command center for managing a milestone. Shows a dashboard of all phases with visual status indicators, recommends optimal next actions, and dispatches work — discuss runs inline, plan/execute run as background agents. + +Designed for power users who want to parallelize work across phases from one terminal: discuss a phase while another plans or executes in the background. + +**Creates/Updates:** +- No files created directly — dispatches to existing GSD commands via skill() and background task agents. +- Reads `.planning/STATE.md`, `.planning/ROADMAP.md`, phase directories for status. + +**After:** User exits when done managing, or all phases complete and milestone lifecycle is suggested. + + + +@$HOME/.config/opencode/get-shit-done/workflows/manager.md +@$HOME/.config/opencode/get-shit-done/references/ui-brand.md + + + +No arguments required. Requires an active milestone with ROADMAP.md and STATE.md. + +Project context, phase list, dependencies, and recommendations are resolved inside the workflow using `gsd-tools.cjs init manager`. No upfront context loading needed. + + + +Execute the manager workflow from @$HOME/.config/opencode/get-shit-done/workflows/manager.md end-to-end. +Maintain the dashboard refresh loop until the user exits or all phases complete. + diff --git a/gsd-opencode/commands/gsd/gsd-milestone-summary.md b/gsd-opencode/commands/gsd/gsd-milestone-summary.md new file mode 100644 index 0000000..6c8cb9b --- /dev/null +++ b/gsd-opencode/commands/gsd/gsd-milestone-summary.md @@ -0,0 +1,51 @@ +--- +type: prompt +name: gsd-milestone-summary +description: Generate a comprehensive project summary from milestone artifacts for team onboarding and review +argument-hint: "[version]" +permissions: + read: true + write: true + bash: true + grep: true + glob: true +--- + + +Generate a structured milestone summary for team onboarding and project review. Reads completed milestone artifacts (ROADMAP, REQUIREMENTS, CONTEXT, SUMMARY, VERIFICATION files) and produces a human-friendly overview of what was built, how, and why. + +Purpose: Enable new team members to understand a completed project by reading one document and asking follow-up questions. +Output: MILESTONE_SUMMARY written to `.planning/reports/`, presented inline, optional interactive Q&A. + + + +@$HOME/.config/opencode/get-shit-done/workflows/milestone-summary.md + + + +**Project files:** +- `.planning/ROADMAP.md` +- `.planning/PROJECT.md` +- `.planning/STATE.md` +- `.planning/RETROSPECTIVE.md` +- `.planning/milestones/v{version}-ROADMAP.md` (if archived) +- `.planning/milestones/v{version}-REQUIREMENTS.md` (if archived) +- `.planning/phases/*-*/` (SUMMARY.md, VERIFICATION.md, CONTEXT.md, RESEARCH.md) + +**User input:** +- Version: $ARGUMENTS (optional — defaults to current/latest milestone) + + + +read and execute the milestone-summary workflow from @$HOME/.config/opencode/get-shit-done/workflows/milestone-summary.md end-to-end. + + + +- Milestone version resolved (from args, STATE.md, or archive scan) +- All available artifacts read (ROADMAP, REQUIREMENTS, CONTEXT, SUMMARY, VERIFICATION, RESEARCH, RETROSPECTIVE) +- Summary document written to `.planning/reports/MILESTONE_SUMMARY-v{version}.md` +- All 7 sections generated (Overview, Architecture, Phases, Decisions, Requirements, Tech Debt, Getting Started) +- Summary presented inline to user +- Interactive Q&A offered +- STATE.md updated + diff --git a/gsd-opencode/commands/gsd/gsd-new-workspace.md b/gsd-opencode/commands/gsd/gsd-new-workspace.md new file mode 100644 index 0000000..f9e6786 --- /dev/null +++ b/gsd-opencode/commands/gsd/gsd-new-workspace.md @@ -0,0 +1,44 @@ +--- +name: gsd-new-workspace +description: Create an isolated workspace with repo copies and independent .planning/ +argument-hint: "--name [--repos repo1,repo2] [--path /target] [--strategy worktree|clone] [--branch name] [--auto]" +permissions: + read: true + bash: true + write: true + question: true +--- + +**Flags:** +- `--name` (required) — Workspace name +- `--repos` — Comma-separated repo paths or names. If omitted, interactive selection from child git repos in cwd +- `--path` — Target directory. Defaults to `~/gsd-workspaces/` +- `--strategy` — `worktree` (default, lightweight) or `clone` (fully independent) +- `--branch` — Branch to checkout. Defaults to `workspace/` +- `--auto` — Skip interactive questions, use defaults + + + +Create a physical workspace directory containing copies of specified git repos (as worktrees or clones) with an independent `.planning/` directory for isolated GSD sessions. + +**Use cases:** +- Multi-repo orchestration: work on a subset of repos in parallel with isolated GSD state +- Feature branch isolation: create a worktree of the current repo with its own `.planning/` + +**Creates:** +- `/WORKSPACE.md` — workspace manifest +- `/.planning/` — independent planning directory +- `//` — git worktree or clone for each specified repo + +**After this command:** `cd` into the workspace and run `/gsd-new-project` to initialize GSD. + + + +@$HOME/.config/opencode/get-shit-done/workflows/new-workspace.md +@$HOME/.config/opencode/get-shit-done/references/ui-brand.md + + + +Execute the new-workspace workflow from @$HOME/.config/opencode/get-shit-done/workflows/new-workspace.md end-to-end. +Preserve all workflow gates (validation, approvals, commits, routing). + diff --git a/gsd-opencode/commands/gsd/gsd-next.md b/gsd-opencode/commands/gsd/gsd-next.md new file mode 100644 index 0000000..b2d1f80 --- /dev/null +++ b/gsd-opencode/commands/gsd/gsd-next.md @@ -0,0 +1,24 @@ +--- +name: gsd-next +description: Automatically advance to the next logical step in the GSD workflow +permissions: + read: true + bash: true + grep: true + glob: true + task: true +--- + +Detect the current project state and automatically invoke the next logical GSD workflow step. +No arguments needed — reads STATE.md, ROADMAP.md, and phase directories to determine what comes next. + +Designed for rapid multi-project workflows where remembering which phase/step you're on is overhead. + + + +@$HOME/.config/opencode/get-shit-done/workflows/next.md + + + +Execute the next workflow from @$HOME/.config/opencode/get-shit-done/workflows/next.md end-to-end. + diff --git a/gsd-opencode/commands/gsd/gsd-note.md b/gsd-opencode/commands/gsd/gsd-note.md new file mode 100644 index 0000000..cf6370b --- /dev/null +++ b/gsd-opencode/commands/gsd/gsd-note.md @@ -0,0 +1,34 @@ +--- +name: gsd-note +description: Zero-friction idea capture. Append, list, or promote notes to todos. +argument-hint: " | list | promote [--global]" +permissions: + read: true + write: true + glob: true + grep: true +--- + +Zero-friction idea capture — one write call, one confirmation line. + +Three subcommands: +- **append** (default): Save a timestamped note file. No questions, no formatting. +- **list**: Show all notes from project and global scopes. +- **promote**: Convert a note into a structured todo. + +Runs inline — no task, no question, no bash. + + + +@$HOME/.config/opencode/get-shit-done/workflows/note.md +@$HOME/.config/opencode/get-shit-done/references/ui-brand.md + + + +$ARGUMENTS + + + +Execute the note workflow from @$HOME/.config/opencode/get-shit-done/workflows/note.md end-to-end. +Capture the note, list notes, or promote to todo — depending on arguments. + diff --git a/gsd-opencode/commands/gsd/gsd-plan-phase.md b/gsd-opencode/commands/gsd/gsd-plan-phase.md index b4fd8bd..26afef0 100644 --- a/gsd-opencode/commands/gsd/gsd-plan-phase.md +++ b/gsd-opencode/commands/gsd/gsd-plan-phase.md @@ -1,7 +1,7 @@ --- name: gsd-plan-phase description: Create detailed phase plan (PLAN.md) with verification loop -argument-hint: "[phase] [--auto] [--research] [--skip-research] [--gaps] [--skip-verify] [--prd ]" +argument-hint: "[phase] [--auto] [--research] [--skip-research] [--gaps] [--skip-verify] [--prd ] [--reviews] [--text]" agent: gsd-planner permissions: read: true @@ -35,6 +35,8 @@ Phase number: $ARGUMENTS (optional — auto-detects next unplanned phase if omit - `--gaps` — Gap closure mode (reads VERIFICATION.md, skips research) - `--skip-verify` — Skip verification loop - `--prd ` — Use a PRD/acceptance criteria file instead of discuss-phase. Parses requirements into CONTEXT.md automatically. Skips discuss-phase entirely. +- `--reviews` — Replan incorporating cross-AI review feedback from REVIEWS.md (produced by `/gsd-review`) +- `--text` — Use plain-text numbered lists instead of TUI menus (required for `/rc` remote sessions) Normalize phase input in step 2 before any directory lookups. diff --git a/gsd-opencode/commands/gsd/gsd-plant-seed.md b/gsd-opencode/commands/gsd/gsd-plant-seed.md new file mode 100644 index 0000000..1415cc2 --- /dev/null +++ b/gsd-opencode/commands/gsd/gsd-plant-seed.md @@ -0,0 +1,28 @@ +--- +name: gsd-plant-seed +description: Capture a forward-looking idea with trigger conditions — surfaces automatically at the right milestone +argument-hint: "[idea summary]" +permissions: + read: true + write: true + edit: true + bash: true + question: true +--- + + +Capture an idea that's too big for now but should surface automatically when the right +milestone arrives. Seeds solve context rot: instead of a one-liner in Deferred that nobody +reads, a seed preserves the full WHY, WHEN to surface, and breadcrumbs to details. + +Creates: .planning/seeds/SEED-NNN-slug.md +Consumed by: /gsd-new-milestone (scans seeds and presents matches) + + + +@$HOME/.config/opencode/get-shit-done/workflows/plant-seed.md + + + +Execute the plant-seed workflow from @$HOME/.config/opencode/get-shit-done/workflows/plant-seed.md end-to-end. + diff --git a/gsd-opencode/commands/gsd/gsd-pr-branch.md b/gsd-opencode/commands/gsd/gsd-pr-branch.md new file mode 100644 index 0000000..fdd77f0 --- /dev/null +++ b/gsd-opencode/commands/gsd/gsd-pr-branch.md @@ -0,0 +1,25 @@ +--- +name: gsd-pr-branch +description: Create a clean PR branch by filtering out .planning/ commits — ready for code review +argument-hint: "[target branch, default: main]" +permissions: + bash: true + read: true + question: true +--- + + +Create a clean branch suitable for pull requests by filtering out .planning/ commits +from the current branch. Reviewers see only code changes, not GSD planning artifacts. + +This solves the problem of PR diffs being cluttered with PLAN.md, SUMMARY.md, STATE.md +changes that are irrelevant to code review. + + + +@$HOME/.config/opencode/get-shit-done/workflows/pr-branch.md + + + +Execute the pr-branch workflow from @$HOME/.config/opencode/get-shit-done/workflows/pr-branch.md end-to-end. + diff --git a/gsd-opencode/commands/gsd/gsd-profile-user.md b/gsd-opencode/commands/gsd/gsd-profile-user.md new file mode 100644 index 0000000..4d31727 --- /dev/null +++ b/gsd-opencode/commands/gsd/gsd-profile-user.md @@ -0,0 +1,46 @@ +--- +name: gsd-profile-user +description: Generate developer behavioral profile and create OpenCode-discoverable artifacts +argument-hint: "[--questionnaire] [--refresh]" +permissions: + read: true + write: true + bash: true + glob: true + grep: true + question: true + task: true +--- + + +Generate a developer behavioral profile from session analysis (or questionnaire) and produce artifacts (USER-PROFILE.md, /gsd-dev-preferences, AGENTS.md section) that personalize OpenCode's responses. + +Routes to the profile-user workflow which orchestrates the full flow: consent gate, session analysis or questionnaire fallback, profile generation, result display, and artifact selection. + + + +@$HOME/.config/opencode/get-shit-done/workflows/profile-user.md +@$HOME/.config/opencode/get-shit-done/references/ui-brand.md + + + +Flags from $ARGUMENTS: +- `--questionnaire` -- Skip session analysis entirely, use questionnaire-only path +- `--refresh` -- Rebuild profile even when one exists, backup old profile, show dimension diff + + + +Execute the profile-user workflow end-to-end. + +The workflow handles all logic including: +1. Initialization and existing profile detection +2. Consent gate before session analysis +3. Session scanning and data sufficiency checks +4. Session analysis (profiler agent) or questionnaire fallback +5. Cross-project split resolution +6. Profile writing to USER-PROFILE.md +7. Result display with report card and highlights +8. Artifact selection (dev-preferences, AGENTS.md sections) +9. Sequential artifact generation +10. Summary with refresh diff (if applicable) + diff --git a/gsd-opencode/commands/gsd/gsd-quick.md b/gsd-opencode/commands/gsd/gsd-quick.md index 7918a25..c0fb500 100644 --- a/gsd-opencode/commands/gsd/gsd-quick.md +++ b/gsd-opencode/commands/gsd/gsd-quick.md @@ -1,7 +1,7 @@ --- name: gsd-quick description: Execute a quick task with GSD guarantees (atomic commits, state tracking) but skip optional agents -argument-hint: "[--full] [--discuss]" +argument-hint: "[--full] [--discuss] [--research]" permissions: read: true write: true @@ -26,7 +26,9 @@ Quick mode is the same system with a shorter path: **`--full` flag:** Enables plan-checking (max 2 iterations) and post-execution verification. Use when you want quality guarantees without full milestone ceremony. -Flags are composable: `--discuss --full` gives discussion + plan-checking + verification. +**`--research` flag:** Spawns a focused research agent before planning. Investigates implementation approaches, library options, and pitfalls for the task. Use when you're unsure of the best approach. + +Flags are composable: `--discuss --research --full` gives discussion + research + plan-checking + verification. diff --git a/gsd-opencode/commands/gsd/gsd-reapply-patches.md b/gsd-opencode/commands/gsd/gsd-reapply-patches.md index b4acf91..5edfae6 100644 --- a/gsd-opencode/commands/gsd/gsd-reapply-patches.md +++ b/gsd-opencode/commands/gsd/gsd-reapply-patches.md @@ -1,18 +1,19 @@ --- name: gsd-reapply-patches description: Reapply local modifications after a GSD update -permissions: read, write, edit, bash, glob, grep, question +permissions: + read: true + write: true + edit: true + bash: true + glob: true + grep: true + question: true --- -Reapply user's local modifications to files after a GSD update reinstalls clean versions. - -When GSD performs updates, it backs up user modifications to a patches directory. This command intelligently merges those modifications back into the new file versions, handling cases where both the upstream code and user modifications may have changed. - - - After a GSD update wipes and reinstalls files, this command merges user's previously saved local modifications back into the new version. Uses intelligent comparison to handle cases where the upstream file also changed. - + diff --git a/gsd-opencode/commands/gsd/gsd-remove-workspace.md b/gsd-opencode/commands/gsd/gsd-remove-workspace.md new file mode 100644 index 0000000..532aa55 --- /dev/null +++ b/gsd-opencode/commands/gsd/gsd-remove-workspace.md @@ -0,0 +1,26 @@ +--- +name: gsd-remove-workspace +description: Remove a GSD workspace and clean up worktrees +argument-hint: "" +permissions: + bash: true + read: true + question: true +--- + +**Arguments:** +- `` (required) — Name of the workspace to remove + + + +Remove a workspace directory after confirmation. For worktree strategy, runs `git worktree remove` for each member repo first. Refuses if any repo has uncommitted changes. + + + +@$HOME/.config/opencode/get-shit-done/workflows/remove-workspace.md +@$HOME/.config/opencode/get-shit-done/references/ui-brand.md + + + +Execute the remove-workspace workflow from @$HOME/.config/opencode/get-shit-done/workflows/remove-workspace.md end-to-end. + diff --git a/gsd-opencode/commands/gsd/gsd-research-phase.md b/gsd-opencode/commands/gsd/gsd-research-phase.md index 4b86510..32378b9 100644 --- a/gsd-opencode/commands/gsd/gsd-research-phase.md +++ b/gsd-opencode/commands/gsd/gsd-research-phase.md @@ -23,6 +23,11 @@ Research how to implement a phase. Spawns gsd-phase-researcher agent with phase **Why subagent:** Research burns context fast (websearch, Context7 queries, source verification). Fresh 200k context for investigation. Main context stays lean for user interaction. + +Valid GSD subagent types (use exact names — do not fall back to 'general'): +- gsd-phase-researcher — Researches technical approaches for a phase + + Phase number: $ARGUMENTS (required) diff --git a/gsd-opencode/commands/gsd/gsd-review-backlog.md b/gsd-opencode/commands/gsd/gsd-review-backlog.md new file mode 100644 index 0000000..0b4d0ba --- /dev/null +++ b/gsd-opencode/commands/gsd/gsd-review-backlog.md @@ -0,0 +1,61 @@ +--- +name: gsd-review-backlog +description: Review and promote backlog items to active milestone +permissions: + read: true + write: true + bash: true +--- + + +Review all 999.x backlog items and optionally promote them into the active +milestone sequence or remove stale entries. + + + + +1. **List backlog items:** + ```bash + ls -d .planning/phases/999* 2>/dev/null || echo "No backlog items found" + ``` + +2. **read ROADMAP.md** and extract all 999.x phase entries: + ```bash + cat .planning/ROADMAP.md + ``` + Show each backlog item with its description, any accumulated context (CONTEXT.md, RESEARCH.md), and creation date. + +3. **Present the list to the user** via question: + - For each backlog item, show: phase number, description, accumulated artifacts + - Options per item: **Promote** (move to active), **Keep** (leave in backlog), **Remove** (delete) + +4. **For items to PROMOTE:** + - Find the next sequential phase number in the active milestone + - Rename the directory from `999.x-slug` to `{new_num}-slug`: + ```bash + NEW_NUM=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" phase add "${DESCRIPTION}" --raw) + ``` + - Move accumulated artifacts to the new phase directory + - Update ROADMAP.md: move the entry from `## Backlog` section to the active phase list + - Remove `(BACKLOG)` marker + - Add appropriate `**Depends on:**` field + +5. **For items to REMOVE:** + - Delete the phase directory + - Remove the entry from ROADMAP.md `## Backlog` section + +6. **Commit changes:** + ```bash + node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: review backlog — promoted N, removed M" --files .planning/ROADMAP.md + ``` + +7. **Report summary:** + ``` + ## 📋 Backlog Review Complete + + Promoted: {list of promoted items with new phase numbers} + Kept: {list of items remaining in backlog} + Removed: {list of deleted items} + ``` + + diff --git a/gsd-opencode/commands/gsd/gsd-review.md b/gsd-opencode/commands/gsd/gsd-review.md new file mode 100644 index 0000000..156f6c0 --- /dev/null +++ b/gsd-opencode/commands/gsd/gsd-review.md @@ -0,0 +1,37 @@ +--- +name: gsd-review +description: Request cross-AI peer review of phase plans from external AI CLIs +argument-hint: "--phase N [--gemini] [--OpenCode] [--codex] [--all]" +permissions: + read: true + write: true + bash: true + glob: true + grep: true +--- + + +Invoke external AI CLIs (Gemini, OpenCode, Codex) to independently review phase plans. +Produces a structured REVIEWS.md with per-reviewer feedback that can be fed back into +planning via /gsd-plan-phase --reviews. + +**Flow:** Detect CLIs → Build review prompt → Invoke each CLI → Collect responses → write REVIEWS.md + + + +@$HOME/.config/opencode/get-shit-done/workflows/review.md + + + +Phase number: extracted from $ARGUMENTS (required) + +**Flags:** +- `--gemini` — Include Gemini CLI review +- `--OpenCode` — Include OpenCode CLI review (uses separate session) +- `--codex` — Include Codex CLI review +- `--all` — Include all available CLIs + + + +Execute the review workflow from @$HOME/.config/opencode/get-shit-done/workflows/review.md end-to-end. + diff --git a/gsd-opencode/commands/gsd/gsd-session-report.md b/gsd-opencode/commands/gsd/gsd-session-report.md new file mode 100644 index 0000000..ddd380a --- /dev/null +++ b/gsd-opencode/commands/gsd/gsd-session-report.md @@ -0,0 +1,19 @@ +--- +name: gsd-session-report +description: Generate a session report with token usage estimates, work summary, and outcomes +permissions: + read: true + bash: true + write: true +--- + +Generate a structured SESSION_REPORT.md document capturing session outcomes, work performed, and estimated resource usage. Provides a shareable artifact for post-session review. + + + +@$HOME/.config/opencode/get-shit-done/workflows/session-report.md + + + +Execute the session-report workflow from @$HOME/.config/opencode/get-shit-done/workflows/session-report.md end-to-end. + diff --git a/gsd-opencode/commands/gsd/gsd-set-profile.md b/gsd-opencode/commands/gsd/gsd-set-profile.md index 9b84ba3..a6075e5 100644 --- a/gsd-opencode/commands/gsd/gsd-set-profile.md +++ b/gsd-opencode/commands/gsd/gsd-set-profile.md @@ -1,34 +1,35 @@ --- name: gsd-set-profile -description: Switch model profile for GSD agents (simple/smart/genius) -argument-hint: +description: Switch model profile for GSD agents (simple/smart/genius/inherit) +argument-hint: +model: haiku permissions: - read: true - write: true bash: true --- + + -Switch the model profile used by GSD agents. Controls which OpenCode model each agent uses, balancing quality vs token spend. + Switch the model profile used by GSD agents. Controls which OpenCode model each agent uses, balancing quality vs token spend. -Routes to the set-profile workflow which handles: -- Argument validation (simple/smart/genius) -- Config file creation if missing -- Profile update in config.json -- Confirmation with model table display - + Routes to the set-profile workflow which handles: + - Argument validation (simple/smart/genius) + - Config file creation if missing + - Profile update in config.json + - Confirmation with model table display + - -@$HOME/.config/opencode/get-shit-done/workflows/oc-set-profile.md - + + @$HOME/.config/opencode/get-shit-done/workflows/oc-set-profile.md + - -**Follow the set-profile workflow** from `@$HOME/.config/opencode/get-shit-done/workflows/oc-set-profile.md`. + + **Follow the set-profile workflow** from `@$HOME/.config/opencode/get-shit-done/workflows/oc-set-profile.md`. -The workflow handles all logic including: -1. Profile argument validation -2. Config file ensuring -3. Config reading and updating -4. Model table generation from MODEL_PROFILES -5. Confirmation display - + The workflow handles all logic including: + 1. Profile argument validation + 2. Config file ensuring + 3. Config reading and updating + 4. Model table generation from MODEL_PROFILES + 5. Confirmation display + diff --git a/gsd-opencode/commands/gsd/gsd-ship.md b/gsd-opencode/commands/gsd/gsd-ship.md new file mode 100644 index 0000000..cce8476 --- /dev/null +++ b/gsd-opencode/commands/gsd/gsd-ship.md @@ -0,0 +1,23 @@ +--- +name: gsd-ship +description: Create PR, run review, and prepare for merge after verification passes +argument-hint: "[phase number or milestone, e.g., '4' or 'v1.0']" +permissions: + read: true + bash: true + grep: true + glob: true + write: true + question: true +--- + +Bridge local completion → merged PR. After /gsd-verify-work passes, ship the work: push branch, create PR with auto-generated body, optionally trigger review, and track the merge. + +Closes the plan → execute → verify → ship loop. + + + +@$HOME/.config/opencode/get-shit-done/workflows/ship.md + + +Execute the ship workflow from @$HOME/.config/opencode/get-shit-done/workflows/ship.md end-to-end. diff --git a/gsd-opencode/commands/gsd/gsd-stats.md b/gsd-opencode/commands/gsd/gsd-stats.md new file mode 100644 index 0000000..84277e6 --- /dev/null +++ b/gsd-opencode/commands/gsd/gsd-stats.md @@ -0,0 +1,18 @@ +--- +name: gsd-stats +description: Display project statistics — phases, plans, requirements, git metrics, and timeline +permissions: + read: true + bash: true +--- + +Display comprehensive project statistics including phase progress, plan execution metrics, requirements completion, git history stats, and project timeline. + + + +@$HOME/.config/opencode/get-shit-done/workflows/stats.md + + + +Execute the stats workflow from @$HOME/.config/opencode/get-shit-done/workflows/stats.md end-to-end. + diff --git a/gsd-opencode/commands/gsd/gsd-thread.md b/gsd-opencode/commands/gsd/gsd-thread.md new file mode 100644 index 0000000..fafd656 --- /dev/null +++ b/gsd-opencode/commands/gsd/gsd-thread.md @@ -0,0 +1,127 @@ +--- +name: gsd-thread +description: Manage persistent context threads for cross-session work +argument-hint: [name | description] +permissions: + read: true + write: true + bash: true +--- + + +Create, list, or resume persistent context threads. Threads are lightweight +cross-session knowledge stores for work that spans multiple sessions but +doesn't belong to any specific phase. + + + + +**Parse $ARGUMENTS to determine mode:** + + +**If no arguments or $ARGUMENTS is empty:** + +List all threads: +```bash +ls .planning/threads/*.md 2>/dev/null +``` + +For each thread, read the first few lines to show title and status: +``` +## Active Threads + +| Thread | Status | Last Updated | +|--------|--------|-------------| +| fix-deploy-key-auth | OPEN | 2026-03-15 | +| pasta-tcp-timeout | RESOLVED | 2026-03-12 | +| perf-investigation | IN PROGRESS | 2026-03-17 | +``` + +If no threads exist, show: +``` +No threads found. Create one with: /gsd-thread +``` + + + +**If $ARGUMENTS matches an existing thread name (file exists):** + +Resume the thread — load its context into the current session: +```bash +cat ".planning/threads/${THREAD_NAME}.md" +``` + +Display the thread content and ask what the user wants to work on next. +Update the thread's status to `IN PROGRESS` if it was `OPEN`. + + + +**If $ARGUMENTS is a new description (no matching thread file):** + +Create a new thread: + +1. Generate slug from description: + ```bash + SLUG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" generate-slug "$ARGUMENTS") + ``` + +2. Create the threads directory if needed: + ```bash + mkdir -p .planning/threads + ``` + +3. write the thread file: + ```bash + cat > ".planning/threads/${SLUG}.md" << 'EOF' + # Thread: {description} + + ## Status: OPEN + + ## Goal + + {description} + + ## Context + + *Created from conversation on {today's date}.* + + ## References + + - *(add links, file paths, or issue numbers)* + + ## Next Steps + + - *(what the next session should do first)* + EOF + ``` + +4. If there's relevant context in the current conversation (code snippets, + error messages, investigation results), extract and add it to the Context + section. + +5. Commit: + ```bash + node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: create thread — ${ARGUMENTS}" --files ".planning/threads/${SLUG}.md" + ``` + +6. Report: + ``` + ## 🧵 Thread Created + + Thread: {slug} + File: .planning/threads/{slug}.md + + Resume anytime with: /gsd-thread {slug} + ``` + + + + + +- Threads are NOT phase-scoped — they exist independently of the roadmap +- Lighter weight than /gsd-pause-work — no phase state, no plan context +- The value is in Context and Next Steps — a cold-start session can pick up immediately +- Threads can be promoted to phases or backlog items when they mature: + /gsd-add-phase or /gsd-add-backlog with context from the thread +- Thread files live in .planning/threads/ — no collision with phases or other GSD structures + diff --git a/gsd-opencode/commands/gsd/gsd-ui-phase.md b/gsd-opencode/commands/gsd/gsd-ui-phase.md new file mode 100644 index 0000000..f4cf5f5 --- /dev/null +++ b/gsd-opencode/commands/gsd/gsd-ui-phase.md @@ -0,0 +1,34 @@ +--- +name: gsd-ui-phase +description: Generate UI design contract (UI-SPEC.md) for frontend phases +argument-hint: "[phase]" +permissions: + read: true + write: true + bash: true + glob: true + grep: true + task: true + webfetch: true + question: true + mcp__context7__*: true +--- + +Create a UI design contract (UI-SPEC.md) for a frontend phase. +Orchestrates gsd-ui-researcher and gsd-ui-checker. +Flow: Validate → Research UI → Verify UI-SPEC → Done + + + +@$HOME/.config/opencode/get-shit-done/workflows/ui-phase.md +@$HOME/.config/opencode/get-shit-done/references/ui-brand.md + + + +Phase number: $ARGUMENTS — optional, auto-detects next unplanned phase if omitted. + + + +Execute @$HOME/.config/opencode/get-shit-done/workflows/ui-phase.md end-to-end. +Preserve all workflow gates. + diff --git a/gsd-opencode/commands/gsd/gsd-ui-review.md b/gsd-opencode/commands/gsd/gsd-ui-review.md new file mode 100644 index 0000000..2ba3fd4 --- /dev/null +++ b/gsd-opencode/commands/gsd/gsd-ui-review.md @@ -0,0 +1,32 @@ +--- +name: gsd-ui-review +description: Retroactive 6-pillar visual audit of implemented frontend code +argument-hint: "[phase]" +permissions: + read: true + write: true + bash: true + glob: true + grep: true + task: true + question: true +--- + +Conduct a retroactive 6-pillar visual audit. Produces UI-REVIEW.md with +graded assessment (1-4 per pillar). Works on any project. +Output: {phase_num}-UI-REVIEW.md + + + +@$HOME/.config/opencode/get-shit-done/workflows/ui-review.md +@$HOME/.config/opencode/get-shit-done/references/ui-brand.md + + + +Phase: $ARGUMENTS — optional, defaults to last completed phase. + + + +Execute @$HOME/.config/opencode/get-shit-done/workflows/ui-review.md end-to-end. +Preserve all workflow gates. + diff --git a/gsd-opencode/commands/gsd/gsd-workstreams.md b/gsd-opencode/commands/gsd/gsd-workstreams.md new file mode 100644 index 0000000..71c77aa --- /dev/null +++ b/gsd-opencode/commands/gsd/gsd-workstreams.md @@ -0,0 +1,66 @@ +--- +name: gsd-workstreams +description: Manage parallel workstreams — list, create, switch, status, progress, complete, and resume +--- + +# /gsd-workstreams + + +Manage parallel workstreams for concurrent milestone work. + + +## Usage + +`/gsd-workstreams [subcommand] [args]` + +### Subcommands + +| Command | Description | +|---------|-------------| +| `list` | List all workstreams with status | +| `create ` | Create a new workstream | +| `status ` | Detailed status for one workstream | +| `switch ` | Set active workstream | +| `progress` | Progress summary across all workstreams | +| `complete ` | Archive a completed workstream | +| `resume ` | Resume work in a workstream | + +## Step 1: Parse Subcommand + +Parse the user's input to determine which workstream operation to perform. +If no subcommand given, default to `list`. + +## Step 2: Execute Operation + +### list +Run: `node "$GSD_TOOLS" workstream list --raw --cwd "$CWD"` +Display the workstreams in a table format showing name, status, current phase, and progress. + +### create +Run: `node "$GSD_TOOLS" workstream create --raw --cwd "$CWD"` +After creation, display the new workstream path and suggest next steps: +- `/gsd-new-milestone --ws ` to set up the milestone + +### status +Run: `node "$GSD_TOOLS" workstream status --raw --cwd "$CWD"` +Display detailed phase breakdown and state information. + +### switch +Run: `node "$GSD_TOOLS" workstream set --raw --cwd "$CWD"` +Also set `GSD_WORKSTREAM` env var for the current session. + +### progress +Run: `node "$GSD_TOOLS" workstream progress --raw --cwd "$CWD"` +Display a progress overview across all workstreams. + +### complete +Run: `node "$GSD_TOOLS" workstream complete --raw --cwd "$CWD"` +Archive the workstream to milestones/. + +### resume +Set the workstream as active and suggest `/gsd-resume-work --ws `. + +## Step 3: Display Results + +Format the JSON output from gsd-tools into a human-readable display. +Include the `${GSD_WS}` flag in any routing suggestions. diff --git a/gsd-opencode/docs/AGENTS.md b/gsd-opencode/docs/AGENTS.md new file mode 100644 index 0000000..fd0cf9f --- /dev/null +++ b/gsd-opencode/docs/AGENTS.md @@ -0,0 +1,428 @@ +# GSD Agent Reference + +> All 18 specialized agents — roles, tools, spawn patterns, and relationships. For architecture context, see [Architecture](ARCHITECTURE.md). + +--- + +## Overview + +GSD uses a multi-agent architecture where thin orchestrators (workflow files) spawn specialized agents with fresh context windows. Each agent has a focused role, limited tool access, and produces specific artifacts. + +### Agent Categories + +| Category | Count | Agents | +|----------|-------|--------| +| Researchers | 3 | project-researcher, phase-researcher, ui-researcher | +| Analyzers | 2 | assumptions-analyzer, advisor-researcher | +| Synthesizers | 1 | research-synthesizer | +| Planners | 1 | planner | +| Roadmappers | 1 | roadmapper | +| Executors | 1 | executor | +| Checkers | 3 | plan-checker, integration-checker, ui-checker | +| Verifiers | 1 | verifier | +| Auditors | 2 | nyquist-auditor, ui-auditor | +| Mappers | 1 | codebase-mapper | +| Debuggers | 1 | debugger | + +--- + +## Agent Details + +### gsd-project-researcher + +**Role:** Researches domain ecosystem before roadmap creation. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-new-project`, `/gsd-new-milestone` | +| **Parallelism** | 4 instances (stack, features, architecture, pitfalls) | +| **Tools** | read, write, bash, grep, glob, websearch, webfetch, mcp (context7) | +| **Model (balanced)** | Sonnet | +| **Produces** | `.planning/research/STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md` | + +**Capabilities:** +- Web search for current ecosystem information +- Context7 MCP integration for library documentation +- Writes research documents directly to disk (reduces orchestrator context load) + +--- + +### gsd-phase-researcher + +**Role:** Researches how to implement a specific phase before planning. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-plan-phase` | +| **Parallelism** | 4 instances (same focus areas as project researcher) | +| **Tools** | read, write, bash, grep, glob, websearch, webfetch, mcp (context7) | +| **Model (balanced)** | Sonnet | +| **Produces** | `{phase}-RESEARCH.md` | + +**Capabilities:** +- Reads CONTEXT.md to focus research on user's decisions +- Investigates implementation patterns for the specific phase domain +- Detects test infrastructure for Nyquist validation mapping + +--- + +### gsd-ui-researcher + +**Role:** Produces UI design contracts for frontend phases. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-ui-phase` | +| **Parallelism** | Single instance | +| **Tools** | read, write, bash, grep, glob, websearch, webfetch, mcp (context7) | +| **Model (balanced)** | Sonnet | +| **Color** | `#E879F9` (fuchsia) | +| **Produces** | `{phase}-UI-SPEC.md` | + +**Capabilities:** +- Detects design system state (shadcn components.json, Tailwind config, existing tokens) +- Offers shadcn initialization for React/Next.js/Vite projects +- Asks only unanswered design contract questions +- Enforces registry safety gate for third-party components + +--- + +### gsd-assumptions-analyzer + +**Role:** Deeply analyzes codebase for a phase and returns structured assumptions with evidence, confidence levels, and consequences if wrong. + +| Property | Value | +|----------|-------| +| **Spawned by** | `discuss-phase-assumptions` workflow (when `workflow.discuss_mode = 'assumptions'`) | +| **Parallelism** | Single instance | +| **Tools** | read, bash, grep, glob | +| **Model (balanced)** | Sonnet | +| **Color** | Cyan | +| **Produces** | Structured assumptions with decision statements, evidence file paths, confidence levels | + +**Key behaviors:** +- Reads ROADMAP.md phase description and prior CONTEXT.md files +- Searches codebase for files related to the phase (components, patterns, similar features) +- Reads 5-15 most relevant source files to form evidence-based assumptions +- Classifies confidence: Confident (clear from code), Likely (reasonable inference), Unclear (could go multiple ways) +- Flags topics that need external research (library compatibility, ecosystem best practices) +- Output calibrated by tier: full_maturity (3-5 areas), standard (3-4), minimal_decisive (2-3) + +--- + +### gsd-advisor-researcher + +**Role:** Researches a single gray area decision during discuss-phase advisor mode and returns a structured comparison table. + +| Property | Value | +|----------|-------| +| **Spawned by** | `discuss-phase` workflow (when ADVISOR_MODE = true) | +| **Parallelism** | Multiple instances (one per gray area) | +| **Tools** | read, bash, grep, glob, websearch, webfetch, mcp (context7) | +| **Model (balanced)** | Sonnet | +| **Color** | Cyan | +| **Produces** | 5-column comparison table (Option / Pros / Cons / Complexity / Recommendation) with rationale paragraph | + +**Key behaviors:** +- Researches a single assigned gray area using OpenCode's knowledge, Context7, and web search +- Produces genuinely viable options — no padding with filler alternatives +- Complexity column uses impact surface + risk (never time estimates) +- Recommendations are conditional ("Rec if X", "Rec if Y") — never single-winner ranking +- Output calibrated by tier: full_maturity (3-5 options with maturity signals), standard (2-4), minimal_decisive (2 options, decisive recommendation) + +--- + +### gsd-research-synthesizer + +**Role:** Combines outputs from parallel researchers into a unified summary. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-new-project` (after 4 researchers complete) | +| **Parallelism** | Single instance (sequential after researchers) | +| **Tools** | read, write, bash | +| **Model (balanced)** | Sonnet | +| **Color** | Purple | +| **Produces** | `.planning/research/SUMMARY.md` | + +--- + +### gsd-planner + +**Role:** Creates executable phase plans with task breakdown, dependency analysis, and goal-backward verification. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-plan-phase`, `/gsd-quick` | +| **Parallelism** | Single instance | +| **Tools** | read, write, bash, glob, grep, webfetch, mcp (context7) | +| **Model (balanced)** | Opus | +| **Color** | Green | +| **Produces** | `{phase}-{N}-PLAN.md` files | + +**Key behaviors:** +- Reads PROJECT.md, REQUIREMENTS.md, CONTEXT.md, RESEARCH.md +- Creates 2-3 atomic task plans sized for single context windows +- Uses XML structure with `` elements +- Includes `read_first` and `acceptance_criteria` sections +- Groups plans into dependency waves + +--- + +### gsd-roadmapper + +**Role:** Creates project roadmaps with phase breakdown and requirement mapping. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-new-project` | +| **Parallelism** | Single instance | +| **Tools** | read, write, bash, glob, grep | +| **Model (balanced)** | Sonnet | +| **Color** | Purple | +| **Produces** | `ROADMAP.md` | + +**Key behaviors:** +- Maps requirements to phases (traceability) +- Derives success criteria from requirements +- Respects granularity setting for phase count +- Validates coverage (every v1 requirement mapped to a phase) + +--- + +### gsd-executor + +**Role:** Executes GSD plans with atomic commits, deviation handling, and checkpoint protocols. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-execute-phase`, `/gsd-quick` | +| **Parallelism** | Multiple (parallel within waves, sequential across waves) | +| **Tools** | read, write, edit, bash, grep, glob | +| **Model (balanced)** | Sonnet | +| **Color** | Yellow | +| **Produces** | Code changes, git commits, `{phase}-{N}-SUMMARY.md` | + +**Key behaviors:** +- Fresh 200K context window per plan +- Follows XML task instructions precisely +- Atomic git commit per completed task +- Handles checkpoint types: auto, human-verify, decision, human-action +- Reports deviations from plan in SUMMARY.md +- Invokes node repair on verification failure + +--- + +### gsd-plan-checker + +**Role:** Verifies plans will achieve phase goals before execution. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-plan-phase` (verification loop, max 3 iterations) | +| **Parallelism** | Single instance (iterative) | +| **Tools** | read, bash, glob, grep | +| **Model (balanced)** | Sonnet | +| **Color** | Green | +| **Produces** | PASS/FAIL verdict with specific feedback | + +**8 Verification Dimensions:** +1. Requirement coverage +2. task atomicity +3. Dependency ordering +4. File scope +5. Verification commands +6. Context fit +7. Gap detection +8. Nyquist compliance (when enabled) + +--- + +### gsd-integration-checker + +**Role:** Verifies cross-phase integration and end-to-end flows. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-audit-milestone` | +| **Parallelism** | Single instance | +| **Tools** | read, bash, grep, glob | +| **Model (balanced)** | Sonnet | +| **Color** | Blue | +| **Produces** | Integration verification report | + +--- + +### gsd-ui-checker + +**Role:** Validates UI-SPEC.md design contracts against quality dimensions. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-ui-phase` (validation loop, max 2 iterations) | +| **Parallelism** | Single instance | +| **Tools** | read, bash, glob, grep | +| **Model (balanced)** | Sonnet | +| **Color** | `#22D3EE` (cyan) | +| **Produces** | BLOCK/FLAG/PASS verdict | + +--- + +### gsd-verifier + +**Role:** Verifies phase goal achievement through goal-backward analysis. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-execute-phase` (after all executors complete) | +| **Parallelism** | Single instance | +| **Tools** | read, write, bash, grep, glob | +| **Model (balanced)** | Sonnet | +| **Color** | Green | +| **Produces** | `{phase}-VERIFICATION.md` | + +**Key behaviors:** +- Checks codebase against phase goals, not just task completion +- PASS/FAIL with specific evidence +- Logs issues for `/gsd-verify-work` to address + +--- + +### gsd-nyquist-auditor + +**Role:** Fills Nyquist validation gaps by generating tests. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-validate-phase` | +| **Parallelism** | Single instance | +| **Tools** | read, write, edit, bash, grep, glob | +| **Model (balanced)** | Sonnet | +| **Produces** | Test files, updated `VALIDATION.md` | + +**Key behaviors:** +- Never modifies implementation code — only test files +- Max 3 attempts per gap +- Flags implementation bugs as escalations for user + +--- + +### gsd-ui-auditor + +**Role:** Retroactive 6-pillar visual audit of implemented frontend code. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-ui-review` | +| **Parallelism** | Single instance | +| **Tools** | read, write, bash, grep, glob | +| **Model (balanced)** | Sonnet | +| **Color** | `#F472B6` (pink) | +| **Produces** | `{phase}-UI-REVIEW.md` with scores | + +**6 Audit Pillars (scored 1-4):** +1. Copywriting +2. Visuals +3. Color +4. Typography +5. Spacing +6. Experience Design + +--- + +### gsd-codebase-mapper + +**Role:** Explores codebase and writes structured analysis documents. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-map-codebase` | +| **Parallelism** | 4 instances (tech, architecture, quality, concerns) | +| **Tools** | read, bash, grep, glob, write | +| **Model (balanced)** | Haiku | +| **Color** | Cyan | +| **Produces** | `.planning/codebase/*.md` (7 documents) | + +**Key behaviors:** +- read-only exploration + structured output +- Writes documents directly to disk +- No reasoning required — pattern extraction from file contents + +--- + +### gsd-debugger + +**Role:** Investigates bugs using scientific method with persistent state. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-debug`, `/gsd-verify-work` (for failures) | +| **Parallelism** | Single instance (interactive) | +| **Tools** | read, write, edit, bash, grep, glob, websearch | +| **Model (balanced)** | Sonnet | +| **Color** | Orange | +| **Produces** | `.planning/debug/*.md`, knowledge-base updates | + +**Debug Session Lifecycle:** +`gathering` → `investigating` → `fixing` → `verifying` → `awaiting_human_verify` → `resolved` + +**Key behaviors:** +- Tracks hypotheses, evidence, and eliminated theories +- State persists across context resets +- Requires human verification before marking resolved +- Appends to persistent knowledge base on resolution +- Consults knowledge base on new sessions + +--- + +### gsd-user-profiler + +**Role:** Analyzes session messages across 8 behavioral dimensions to produce a scored developer profile. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-profile-user` | +| **Parallelism** | Single instance | +| **Tools** | read | +| **Model (balanced)** | Sonnet | +| **Color** | Magenta | +| **Produces** | `USER-PROFILE.md`, `/gsd-dev-preferences`, `AGENTS.md` profile section | + +**Behavioral Dimensions:** +Communication style, decision patterns, debugging approach, UX preferences, vendor choices, frustration triggers, learning style, explanation depth. + +**Key behaviors:** +- read-only agent — analyzes extracted session data, does not modify files +- Produces scored dimensions with confidence levels and evidence citations +- Questionnaire fallback when session history is unavailable + +--- + +## Agent Tool Permissions Summary + +| Agent | read | write | edit | bash | grep | glob | websearch | webfetch | MCP | +|-------|------|-------|------|------|------|------|-----------|----------|-----| +| project-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| phase-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| ui-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| assumptions-analyzer | ✓ | | | ✓ | ✓ | ✓ | | | | +| advisor-researcher | ✓ | | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| research-synthesizer | ✓ | ✓ | | ✓ | | | | | | +| planner | ✓ | ✓ | | ✓ | ✓ | ✓ | | ✓ | ✓ | +| roadmapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | | +| executor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | | +| plan-checker | ✓ | | | ✓ | ✓ | ✓ | | | | +| integration-checker | ✓ | | | ✓ | ✓ | ✓ | | | | +| ui-checker | ✓ | | | ✓ | ✓ | ✓ | | | | +| verifier | ✓ | ✓ | | ✓ | ✓ | ✓ | | | | +| nyquist-auditor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | | +| ui-auditor | ✓ | ✓ | | ✓ | ✓ | ✓ | | | | +| codebase-mapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | | +| debugger | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | +| user-profiler | ✓ | | | | | | | | | + +**Principle of Least Privilege:** +- Checkers are read-only (no write/edit) — they evaluate, never modify +- Researchers have web access — they need current ecosystem information +- Executors have edit — they modify code but not web access +- Mappers have write — they write analysis documents but not edit (no code changes) diff --git a/gsd-opencode/docs/ARCHITECTURE.md b/gsd-opencode/docs/ARCHITECTURE.md new file mode 100644 index 0000000..49c22a1 --- /dev/null +++ b/gsd-opencode/docs/ARCHITECTURE.md @@ -0,0 +1,527 @@ +# GSD Architecture + +> System architecture for contributors and advanced users. For user-facing documentation, see [Feature Reference](FEATURES.md) or [User Guide](USER-GUIDE.md). + +--- + +## Table of Contents + +- [System Overview](#system-overview) +- [Design Principles](#design-principles) +- [Component Architecture](#component-architecture) +- [Agent Model](#agent-model) +- [Data Flow](#data-flow) +- [File System Layout](#file-system-layout) +- [Installer Architecture](#installer-architecture) +- [Hook System](#hook-system) +- [CLI Tools Layer](#cli-tools-layer) +- [Runtime Abstraction](#runtime-abstraction) + +--- + +## System Overview + +GSD is a **meta-prompting framework** that sits between the user and AI coding agents (OpenCode, Gemini CLI, OpenCode, Codex, Copilot, Antigravity). It provides: + +1. **Context engineering** — Structured artifacts that give the AI everything it needs per task +2. **Multi-agent orchestration** — Thin orchestrators that spawn specialized agents with fresh context windows +3. **Spec-driven development** — Requirements → research → plans → execution → verification pipeline +4. **State management** — Persistent project memory across sessions and context resets + +``` +┌──────────────────────────────────────────────────────┐ +│ USER │ +│ /gsd-command [args] │ +└─────────────────────┬────────────────────────────────┘ + │ +┌─────────────────────▼────────────────────────────────┐ +│ COMMAND LAYER │ +│ commands/gsd/*.md — Prompt-based command files │ +│ (OpenCode custom commands / Codex skills) │ +└─────────────────────┬────────────────────────────────┘ + │ +┌─────────────────────▼────────────────────────────────┐ +│ WORKFLOW LAYER │ +│ get-shit-done/workflows/*.md — Orchestration logic │ +│ (Reads references, spawns agents, manages state) │ +└──────┬──────────────┬─────────────────┬──────────────┘ + │ │ │ +┌──────▼──────┐ ┌─────▼─────┐ ┌────────▼───────┐ +│ AGENT │ │ AGENT │ │ AGENT │ +│ (fresh │ │ (fresh │ │ (fresh │ +│ context) │ │ context)│ │ context) │ +└──────┬──────┘ └─────┬─────┘ └────────┬───────┘ + │ │ │ +┌──────▼──────────────▼─────────────────▼──────────────┐ +│ CLI TOOLS LAYER │ +│ get-shit-done/bin/gsd-tools.cjs │ +│ (State, config, phase, roadmap, verify, templates) │ +└──────────────────────┬───────────────────────────────┘ + │ +┌──────────────────────▼───────────────────────────────┐ +│ FILE SYSTEM (.planning/) │ +│ PROJECT.md | REQUIREMENTS.md | ROADMAP.md │ +│ STATE.md | config.json | phases/ | research/ │ +└──────────────────────────────────────────────────────┘ +``` + +--- + +## Design Principles + +### 1. Fresh Context Per Agent + +Every agent spawned by an orchestrator gets a clean context window (up to 200K tokens). This eliminates context rot — the quality degradation that happens as an AI fills its context window with accumulated conversation. + +### 2. Thin Orchestrators + +Workflow files (`get-shit-done/workflows/*.md`) never do heavy lifting. They: +- Load context via `gsd-tools.cjs init ` +- Spawn specialized agents with focused prompts +- Collect results and route to the next step +- Update state between steps + +### 3. File-Based State + +All state lives in `.planning/` as human-readable Markdown and JSON. No database, no server, no external dependencies. This means: +- State survives context resets (`/new`) +- State is inspectable by both humans and agents +- State can be committed to git for team visibility + +### 4. Absent = Enabled + +Workflow feature flags follow the **absent = enabled** pattern. If a key is missing from `config.json`, it defaults to `true`. Users explicitly disable features; they don't need to enable defaults. + +### 5. Defense in Depth + +Multiple layers prevent common failure modes: +- Plans are verified before execution (plan-checker agent) +- Execution produces atomic commits per task +- Post-execution verification checks against phase goals +- UAT provides human verification as final gate + +--- + +## Component Architecture + +### Commands (`commands/gsd/*.md`) + +User-facing entry points. Each file contains YAML frontmatter (name, description, allowed-tools) and a prompt body that bootstraps the workflow. Commands are installed as: +- **OpenCode:** Custom slash commands (`/gsd-command-name`) +- **OpenCode:** Slash commands (`/gsd-command-name`) +- **Codex:** Skills (`$gsd-command-name`) +- **Copilot:** Slash commands (`/gsd-command-name`) +- **Antigravity:** Skills + +**Total commands:** 44 + +### Workflows (`get-shit-done/workflows/*.md`) + +Orchestration logic that commands reference. Contains the step-by-step process including: +- Context loading via `gsd-tools.cjs init` +- Agent spawn instructions with model resolution +- Gate/checkpoint definitions +- State update patterns +- Error handling and recovery + +**Total workflows:** 46 + +### Agents (`agents/*.md`) + +Specialized agent definitions with frontmatter specifying: +- `name` — Agent identifier +- `description` — Role and purpose +- `tools` — Allowed tool access (read, write, edit, bash, grep, glob, websearch, etc.) +- `color` — Terminal output color for visual distinction + +**Total agents:** 16 + +### References (`get-shit-done/references/*.md`) + +Shared knowledge documents that workflows and agents `@-reference`: +- `checkpoints.md` — Checkpoint type definitions and interaction patterns +- `model-profiles.md` — Per-agent model tier assignments +- `verification-patterns.md` — How to verify different artifact types +- `planning-config.md` — Full config schema and behavior +- `git-integration.md` — Git commit, branching, and history patterns +- `questioning.md` — Dream extraction philosophy for project initialization +- `tdd.md` — Test-driven development integration patterns +- `ui-brand.md` — Visual output formatting patterns + +### Templates (`get-shit-done/templates/`) + +Markdown templates for all planning artifacts. Used by `gsd-tools.cjs template fill` and `scaffold` commands to create pre-structured files: +- `project.md`, `requirements.md`, `roadmap.md`, `state.md` — Core project files +- `phase-prompt.md` — Phase execution prompt template +- `summary.md` (+ `summary-minimal.md`, `summary-standard.md`, `summary-complex.md`) — Granularity-aware summary templates +- `DEBUG.md` — Debug session tracking template +- `UI-SPEC.md`, `UAT.md`, `VALIDATION.md` — Specialized verification templates +- `discussion-log.md` — Discussion audit trail template +- `codebase/` — Brownfield mapping templates (stack, architecture, conventions, concerns, structure, testing, integrations) +- `research-project/` — Research output templates (SUMMARY, STACK, FEATURES, ARCHITECTURE, PITFALLS) + +### Hooks (`hooks/`) + +Runtime hooks that integrate with the host AI agent: + +| Hook | Event | Purpose | +|------|-------|---------| +| `gsd-statusline.js` | `statusLine` | Displays model, task, directory, and context usage bar | +| `gsd-context-monitor.js` | `PostToolUse` / `AfterTool` | Injects agent-facing context warnings at 35%/25% remaining | +| `gsd-check-update.js` | `SessionStart` | Background check for new GSD versions | +| `gsd-prompt-guard.js` | `PreToolUse` | Scans `.planning/` writes for prompt injection patterns (advisory) | +| `gsd-workflow-guard.js` | `PreToolUse` | Detects file edits outside GSD workflow context (advisory, opt-in via `hooks.workflow_guard`) | + +### CLI Tools (`get-shit-done/bin/`) + +Node.js CLI utility (`gsd-tools.cjs`) with 17 domain modules: + +| Module | Responsibility | +|--------|---------------| +| `core.cjs` | Error handling, output formatting, shared utilities | +| `state.cjs` | STATE.md parsing, updating, progression, metrics | +| `phase.cjs` | Phase directory operations, decimal numbering, plan indexing | +| `roadmap.cjs` | ROADMAP.md parsing, phase extraction, plan progress | +| `config.cjs` | config.json read/write, section initialization | +| `verify.cjs` | Plan structure, phase completeness, reference, commit validation | +| `template.cjs` | Template selection and filling with variable substitution | +| `frontmatter.cjs` | YAML frontmatter CRUD operations | +| `init.cjs` | Compound context loading for each workflow type | +| `milestone.cjs` | Milestone archival, requirements marking | +| `commands.cjs` | Misc commands (slug, timestamp, todos, scaffolding, stats) | +| `model-profiles.cjs` | Model profile resolution table | +| `security.cjs` | Path traversal prevention, prompt injection detection, safe JSON parsing, shell argument validation | +| `uat.cjs` | UAT file parsing, verification debt tracking, audit-uat support | + +--- + +## Agent Model + +### Orchestrator → Agent Pattern + +``` +Orchestrator (workflow .md) + │ + ├── Load context: gsd-tools.cjs init + │ Returns JSON with: project info, config, state, phase details + │ + ├── Resolve model: gsd-tools.cjs resolve-model + │ Returns: opus | sonnet | haiku | inherit + │ + ├── Spawn Agent (task/SubAgent call) + │ ├── Agent prompt (agents/*.md) + │ ├── Context payload (init JSON) + │ ├── Model assignment + │ └── Tool permissions + │ + ├── Collect result + │ + └── Update state: gsd-tools.cjs state update/patch/advance-plan +``` + +### Agent Spawn Categories + +| Category | Agents | Parallelism | +|----------|--------|-------------| +| **Researchers** | gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher, gsd-advisor-researcher | 4 parallel (stack, features, architecture, pitfalls); advisor spawns during discuss-phase | +| **Synthesizers** | gsd-research-synthesizer | Sequential (after researchers complete) | +| **Planners** | gsd-planner, gsd-roadmapper | Sequential | +| **Checkers** | gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor | Sequential (verification loop, max 3 iterations) | +| **Executors** | gsd-executor | Parallel within waves, sequential across waves | +| **Verifiers** | gsd-verifier | Sequential (after all executors complete) | +| **Mappers** | gsd-codebase-mapper | 4 parallel (tech, arch, quality, concerns) | +| **Debuggers** | gsd-debugger | Sequential (interactive) | +| **Auditors** | gsd-ui-auditor | Sequential | + +### Wave Execution Model + +During `execute-phase`, plans are grouped into dependency waves: + +``` +Wave Analysis: + Plan 01 (no deps) ─┐ + Plan 02 (no deps) ─┤── Wave 1 (parallel) + Plan 03 (depends: 01) ─┤── Wave 2 (waits for Wave 1) + Plan 04 (depends: 02) ─┘ + Plan 05 (depends: 03,04) ── Wave 3 (waits for Wave 2) +``` + +Each executor gets: +- Fresh 200K context window +- The specific PLAN.md to execute +- Project context (PROJECT.md, STATE.md) +- Phase context (CONTEXT.md, RESEARCH.md if available) + +#### Parallel Commit Safety + +When multiple executors run within the same wave, two mechanisms prevent conflicts: + +1. **`--no-verify` commits** — Parallel agents skip pre-commit hooks (which can cause build lock contention, e.g., cargo lock fights in Rust projects). The orchestrator runs `git hook run pre-commit` once after each wave completes. + +2. **STATE.md file locking** — All `writeStateMd()` calls use lockfile-based mutual exclusion (`STATE.md.lock` with `O_EXCL` atomic creation). This prevents the read-modify-write race condition where two agents read STATE.md, modify different fields, and the last writer overwrites the other's changes. Includes stale lock detection (10s timeout) and spin-wait with jitter. + +--- + +## Data Flow + +### New Project Flow + +``` +User input (idea description) + │ + ▼ +Questions (questioning.md philosophy) + │ + ▼ +4x Project Researchers (parallel) + ├── Stack → STACK.md + ├── Features → FEATURES.md + ├── Architecture → ARCHITECTURE.md + └── Pitfalls → PITFALLS.md + │ + ▼ +Research Synthesizer → SUMMARY.md + │ + ▼ +Requirements extraction → REQUIREMENTS.md + │ + ▼ +Roadmapper → ROADMAP.md + │ + ▼ +User approval → STATE.md initialized +``` + +### Phase Execution Flow + +``` +discuss-phase → CONTEXT.md (user preferences) + │ + ▼ +ui-phase → UI-SPEC.md (design contract, optional) + │ + ▼ +plan-phase + ├── Phase Researcher → RESEARCH.md + ├── Planner → PLAN.md files + └── Plan Checker → Verify loop (max 3x) + │ + ▼ +execute-phase + ├── Wave analysis (dependency grouping) + ├── Executor per plan → code + atomic commits + ├── SUMMARY.md per plan + └── Verifier → VERIFICATION.md + │ + ▼ +verify-work → UAT.md (user acceptance testing) + │ + ▼ +ui-review → UI-REVIEW.md (visual audit, optional) +``` + +### Context Propagation + +Each workflow stage produces artifacts that feed into subsequent stages: + +``` +PROJECT.md ────────────────────────────────────────────► All agents +REQUIREMENTS.md ───────────────────────────────────────► Planner, Verifier, Auditor +ROADMAP.md ────────────────────────────────────────────► Orchestrators +STATE.md ──────────────────────────────────────────────► All agents (decisions, blockers) +CONTEXT.md (per phase) ────────────────────────────────► Researcher, Planner, Executor +RESEARCH.md (per phase) ───────────────────────────────► Planner, Plan Checker +PLAN.md (per plan) ────────────────────────────────────► Executor, Plan Checker +SUMMARY.md (per plan) ─────────────────────────────────► Verifier, State tracking +UI-SPEC.md (per phase) ────────────────────────────────► Executor, UI Auditor +``` + +--- + +## File System Layout + +### Installation Files + +``` +$HOME/.config/opencode/ # OpenCode (global install) +├── commands/gsd/*.md # 37 slash commands +├── get-shit-done/ +│ ├── bin/gsd-tools.cjs # CLI utility +│ ├── bin/lib/*.cjs # 15 domain modules +│ ├── workflows/*.md # 42 workflow definitions +│ ├── references/*.md # 13 shared reference docs +│ └── templates/ # Planning artifact templates +├── agents/*.md # 15 agent definitions +├── hooks/ +│ ├── gsd-statusline.js # Statusline hook +│ ├── gsd-context-monitor.js # Context warning hook +│ └── gsd-check-update.js # Update check hook +├── settings.json # Hook registrations +└── VERSION # Installed version number +``` + +Equivalent paths for other runtimes: +- **OpenCode:** `~/.config/opencode/` or `~/.opencode/` +- **Gemini CLI:** `~/.gemini/` +- **Codex:** `~/.codex/` (uses skills instead of commands) +- **Copilot:** `~/.github/` +- **Antigravity:** `~/.gemini/antigravity/` (global) or `./.agent/` (local) + +### Project Files (`.planning/`) + +``` +.planning/ +├── PROJECT.md # Project vision, constraints, decisions, evolution rules +├── REQUIREMENTS.md # Scoped requirements (v1/v2/out-of-scope) +├── ROADMAP.md # Phase breakdown with status tracking +├── STATE.md # Living memory: position, decisions, blockers, metrics +├── config.json # Workflow configuration +├── MILESTONES.md # Completed milestone archive +├── research/ # Domain research from /gsd-new-project +│ ├── SUMMARY.md +│ ├── STACK.md +│ ├── FEATURES.md +│ ├── ARCHITECTURE.md +│ └── PITFALLS.md +├── codebase/ # Brownfield mapping (from /gsd-map-codebase) +│ ├── STACK.md +│ ├── ARCHITECTURE.md +│ ├── CONVENTIONS.md +│ ├── CONCERNS.md +│ ├── STRUCTURE.md +│ ├── TESTING.md +│ └── INTEGRATIONS.md +├── phases/ +│ └── XX-phase-name/ +│ ├── XX-CONTEXT.md # User preferences (from discuss-phase) +│ ├── XX-RESEARCH.md # Ecosystem research (from plan-phase) +│ ├── XX-YY-PLAN.md # Execution plans +│ ├── XX-YY-SUMMARY.md # Execution outcomes +│ ├── XX-VERIFICATION.md # Post-execution verification +│ ├── XX-VALIDATION.md # Nyquist test coverage mapping +│ ├── XX-UI-SPEC.md # UI design contract (from ui-phase) +│ ├── XX-UI-REVIEW.md # Visual audit scores (from ui-review) +│ └── XX-UAT.md # User acceptance test results +├── quick/ # Quick task tracking +│ └── YYMMDD-xxx-slug/ +│ ├── PLAN.md +│ └── SUMMARY.md +├── todos/ +│ ├── pending/ # Captured ideas +│ └── done/ # Completed todos +├── threads/ # Persistent context threads (from /gsd-thread) +├── seeds/ # Forward-looking ideas (from /gsd-plant-seed) +├── debug/ # Active debug sessions +│ ├── *.md # Active sessions +│ ├── resolved/ # Archived sessions +│ └── knowledge-base.md # Persistent debug learnings +├── ui-reviews/ # Screenshots from /gsd-ui-review (gitignored) +└── continue-here.md # Context handoff (from pause-work) +``` + +--- + +## Installer Architecture + +The installer (`bin/install.js`, ~3,000 lines) handles: + +1. **Runtime detection** — Interactive prompt or CLI flags (`--OpenCode`, `--opencode`, `--gemini`, `--codex`, `--copilot`, `--antigravity`, `--all`) +2. **Location selection** — Global (`--global`) or local (`--local`) +3. **File deployment** — Copies commands, workflows, references, templates, agents, hooks +4. **Runtime adaptation** — Transforms file content per runtime: + - OpenCode: Uses as-is + - OpenCode: Converts agent frontmatter to `name:`, `model: inherit`, `mode: subagent` + - Codex: Generates TOML config + skills from commands + - Copilot: Maps tool names (read→read, bash→execute, etc.) + - Gemini: Adjusts hook event names (`AfterTool` instead of `PostToolUse`) + - Antigravity: Skills-first with Google model equivalents +5. **Path normalization** — Replaces `$HOME/.config/opencode/` paths with runtime-specific paths +6. **Settings integration** — Registers hooks in runtime's `settings.json` +7. **patch backup** — Since v1.17, backs up locally modified files to `gsd-local-patches/` for `/gsd-reapply-patches` +8. **Manifest tracking** — Writes `gsd-file-manifest.json` for clean uninstall +9. **Uninstall mode** — `--uninstall` removes all GSD files, hooks, and settings + +### Platform Handling + +- **Windows:** `windowsHide` on child processes, EPERM/EACCES protection on protected directories, path separator normalization +- **WSL:** Detects Windows Node.js running on WSL and warns about path mismatches +- **Docker/CI:** Supports `CLAUDE_CONFIG_DIR` env var for custom config directory locations + +--- + +## Hook System + +### Architecture + +``` +Runtime Engine (OpenCode / Gemini CLI) + │ + ├── statusLine event ──► gsd-statusline.js + │ Reads: stdin (session JSON) + │ Writes: stdout (formatted status), /tmp/OpenCode-ctx-{session}.json (bridge) + │ + ├── PostToolUse/AfterTool event ──► gsd-context-monitor.js + │ Reads: stdin (tool event JSON), /tmp/OpenCode-ctx-{session}.json (bridge) + │ Writes: stdout (hookSpecificOutput with additionalContext warning) + │ + └── SessionStart event ──► gsd-check-update.js + Reads: VERSION file + Writes: $HOME/.config/opencode/cache/gsd-update-check.json (spawns background process) +``` + +### Context Monitor Thresholds + +| Remaining Context | Level | Agent Behavior | +|-------------------|-------|----------------| +| > 35% | Normal | No warning injected | +| ≤ 35% | WARNING | "Avoid starting new complex work" | +| ≤ 25% | CRITICAL | "Context nearly exhausted, inform user" | + +Debounce: 5 tool uses between repeated warnings. Severity escalation (WARNING→CRITICAL) bypasses debounce. + +### Safety Properties + +- All hooks wrap in try/catch, exit silently on error +- stdin timeout guard (3s) prevents hanging on pipe issues +- Stale metrics (>60s old) are ignored +- Missing bridge files handled gracefully (subagents, fresh sessions) +- Context monitor is advisory — never issues imperative commands that override user preferences + +### Security Hooks (v1.27) + +**Prompt Guard** (`gsd-prompt-guard.js`): +- Triggers on write/edit to `.planning/` files +- Scans content for prompt injection patterns (role override, instruction bypass, system tag injection) +- Advisory-only — logs detection, does not block +- Patterns are inlined (subset of `security.cjs`) for hook independence + +**Workflow Guard** (`gsd-workflow-guard.js`): +- Triggers on write/edit to non-`.planning/` files +- Detects edits outside GSD workflow context (no active `/gsd-` command or task subagent) +- Advises using `/gsd-quick` or `/gsd-fast` for state-tracked changes +- Opt-in via `hooks.workflow_guard: true` (default: false) + +--- + +## Runtime Abstraction + +GSD supports 6 AI coding runtimes through a unified command/workflow architecture: + +| Runtime | Command Format | Agent System | Config Location | +|---------|---------------|--------------|-----------------| +| OpenCode | `/gsd-command` | task spawning | `$HOME/.config/opencode/` | +| OpenCode | `/gsd-command` | Subagent mode | `~/.config/opencode/` | +| Gemini CLI | `/gsd-command` | task spawning | `~/.gemini/` | +| Codex | `$gsd-command` | Skills | `~/.codex/` | +| Copilot | `/gsd-command` | Agent delegation | `~/.github/` | +| Antigravity | Skills | Skills | `~/.gemini/antigravity/` | + +### Abstraction Points + +1. **Tool name mapping** — Each runtime has its own tool names (e.g., OpenCode's `bash` → Copilot's `execute`) +2. **Hook event names** — OpenCode uses `PostToolUse`, Gemini uses `AfterTool` +3. **Agent frontmatter** — Each runtime has its own agent definition format +4. **Path conventions** — Each runtime stores config in different directories +5. **Model references** — `inherit` profile lets GSD defer to runtime's model selection + +The installer handles all translation at install time. Workflows and agents are written in OpenCode's native format and transformed during deployment. diff --git a/gsd-opencode/docs/CLI-TOOLS.md b/gsd-opencode/docs/CLI-TOOLS.md new file mode 100644 index 0000000..0dd9572 --- /dev/null +++ b/gsd-opencode/docs/CLI-TOOLS.md @@ -0,0 +1,366 @@ +# GSD CLI Tools Reference + +> Programmatic API reference for `gsd-tools.cjs`. Used by workflows and agents internally. For user-facing commands, see [Command Reference](COMMANDS.md). + +--- + +## Overview + +`gsd-tools.cjs` is a Node.js CLI utility that replaces repetitive inline bash patterns across GSD's ~50 command, workflow, and agent files. It centralizes: config parsing, model resolution, phase lookup, git commits, summary verification, state management, and template operations. + +**Location:** `get-shit-done/bin/gsd-tools.cjs` +**Modules:** 15 domain modules in `get-shit-done/bin/lib/` + +**Usage:** +```bash +node gsd-tools.cjs [args] [--raw] [--cwd ] +``` + +**Global Flags:** +| Flag | Description | +|------|-------------| +| `--raw` | Machine-readable output (JSON or plain text, no formatting) | +| `--cwd ` | Override working directory (for sandboxed subagents) | + +--- + +## State Commands + +Manage `.planning/STATE.md` — the project's living memory. + +```bash +# Load full project config + state as JSON +node gsd-tools.cjs state load + +# Output STATE.md frontmatter as JSON +node gsd-tools.cjs state json + +# Update a single field +node gsd-tools.cjs state update + +# Get STATE.md content or a specific section +node gsd-tools.cjs state get [section] + +# Batch update multiple fields +node gsd-tools.cjs state patch --field1 val1 --field2 val2 + +# Increment plan counter +node gsd-tools.cjs state advance-plan + +# Record execution metrics +node gsd-tools.cjs state record-metric --phase N --plan M --duration Xmin [--tasks N] [--files N] + +# Recalculate progress bar +node gsd-tools.cjs state update-progress + +# Add a decision +node gsd-tools.cjs state add-decision --summary "..." [--phase N] [--rationale "..."] +# Or from files: +node gsd-tools.cjs state add-decision --summary-file path [--rationale-file path] + +# Add/resolve blockers +node gsd-tools.cjs state add-blocker --text "..." +node gsd-tools.cjs state resolve-blocker --text "..." + +# Record session continuity +node gsd-tools.cjs state record-session --stopped-at "..." [--resume-file path] +``` + +### State Snapshot + +Structured parse of the full STATE.md: + +```bash +node gsd-tools.cjs state-snapshot +``` + +Returns JSON with: current position, phase, plan, status, decisions, blockers, metrics, last activity. + +--- + +## Phase Commands + +Manage phases — directories, numbering, and roadmap sync. + +```bash +# Find phase directory by number +node gsd-tools.cjs find-phase + +# Calculate next decimal phase number for insertions +node gsd-tools.cjs phase next-decimal + +# Append new phase to roadmap + create directory +node gsd-tools.cjs phase add + +# Insert decimal phase after existing +node gsd-tools.cjs phase insert + +# Remove phase, renumber subsequent +node gsd-tools.cjs phase remove [--force] + +# Mark phase complete, update state + roadmap +node gsd-tools.cjs phase complete + +# Index plans with waves and status +node gsd-tools.cjs phase-plan-index + +# List phases with filtering +node gsd-tools.cjs phases list [--type planned|executed|all] [--phase N] [--include-archived] +``` + +--- + +## Roadmap Commands + +Parse and update `ROADMAP.md`. + +```bash +# Extract phase section from ROADMAP.md +node gsd-tools.cjs roadmap get-phase + +# Full roadmap parse with disk status +node gsd-tools.cjs roadmap analyze + +# Update progress table row from disk +node gsd-tools.cjs roadmap update-plan-progress +``` + +--- + +## Config Commands + +read and write `.planning/config.json`. + +```bash +# Initialize config.json with defaults +node gsd-tools.cjs config-ensure-section + +# Set a config value (dot notation) +node gsd-tools.cjs config-set + +# Get a config value +node gsd-tools.cjs config-get + +# Set model profile +node gsd-tools.cjs config-set-model-profile +``` + +--- + +## Model Resolution + +```bash +# Get model for agent based on current profile +node gsd-tools.cjs resolve-model +# Returns: opus | sonnet | haiku | inherit +``` + +Agent names: `gsd-planner`, `gsd-executor`, `gsd-phase-researcher`, `gsd-project-researcher`, `gsd-research-synthesizer`, `gsd-verifier`, `gsd-plan-checker`, `gsd-integration-checker`, `gsd-roadmapper`, `gsd-debugger`, `gsd-codebase-mapper`, `gsd-nyquist-auditor` + +--- + +## Verification Commands + +Validate plans, phases, references, and commits. + +```bash +# Verify SUMMARY.md file +node gsd-tools.cjs verify-summary [--check-count N] + +# Check PLAN.md structure + tasks +node gsd-tools.cjs verify plan-structure + +# Check all plans have summaries +node gsd-tools.cjs verify phase-completeness + +# Check @-refs + paths resolve +node gsd-tools.cjs verify references + +# Batch verify commit hashes +node gsd-tools.cjs verify commits [hash2] ... + +# Check must_haves.artifacts +node gsd-tools.cjs verify artifacts + +# Check must_haves.key_links +node gsd-tools.cjs verify key-links +``` + +--- + +## Validation Commands + +Check project integrity. + +```bash +# Check phase numbering, disk/roadmap sync +node gsd-tools.cjs validate consistency + +# Check .planning/ integrity, optionally repair +node gsd-tools.cjs validate health [--repair] +``` + +--- + +## Template Commands + +Template selection and filling. + +```bash +# Select summary template based on granularity +node gsd-tools.cjs template select + +# Fill template with variables +node gsd-tools.cjs template fill --phase N [--plan M] [--name "..."] [--type execute|tdd] [--wave N] [--fields '{json}'] +``` + +Template types for `fill`: `summary`, `plan`, `verification` + +--- + +## Frontmatter Commands + +YAML frontmatter CRUD operations on any Markdown file. + +```bash +# Extract frontmatter as JSON +node gsd-tools.cjs frontmatter get [--field key] + +# Update single field +node gsd-tools.cjs frontmatter set --field key --value jsonVal + +# Merge JSON into frontmatter +node gsd-tools.cjs frontmatter merge --data '{json}' + +# Validate required fields +node gsd-tools.cjs frontmatter validate --schema plan|summary|verification +``` + +--- + +## Scaffold Commands + +Create pre-structured files and directories. + +```bash +# Create CONTEXT.md template +node gsd-tools.cjs scaffold context --phase N + +# Create UAT.md template +node gsd-tools.cjs scaffold uat --phase N + +# Create VERIFICATION.md template +node gsd-tools.cjs scaffold verification --phase N + +# Create phase directory +node gsd-tools.cjs scaffold phase-dir --phase N --name "phase name" +``` + +--- + +## Init Commands (Compound Context Loading) + +Load all context needed for a specific workflow in one call. Returns JSON with project info, config, state, and workflow-specific data. + +```bash +node gsd-tools.cjs init execute-phase +node gsd-tools.cjs init plan-phase +node gsd-tools.cjs init new-project +node gsd-tools.cjs init new-milestone +node gsd-tools.cjs init quick +node gsd-tools.cjs init resume +node gsd-tools.cjs init verify-work +node gsd-tools.cjs init phase-op +node gsd-tools.cjs init todos [area] +node gsd-tools.cjs init milestone-op +node gsd-tools.cjs init map-codebase +node gsd-tools.cjs init progress +``` + +**Large payload handling:** When output exceeds ~50KB, the CLI writes to a temp file and returns `@file:/tmp/gsd-init-XXXXX.json`. Workflows check for the `@file:` prefix and read from disk: + +```bash +INIT=$(node gsd-tools.cjs init execute-phase "1") +if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +``` + +--- + +## Milestone Commands + +```bash +# Archive milestone +node gsd-tools.cjs milestone complete [--name ] [--archive-phases] + +# Mark requirements as complete +node gsd-tools.cjs requirements mark-complete +# Accepts: REQ-01,REQ-02 or REQ-01 REQ-02 or [REQ-01, REQ-02] +``` + +--- + +## Utility Commands + +```bash +# Convert text to URL-safe slug +node gsd-tools.cjs generate-slug "Some Text Here" +# → some-text-here + +# Get timestamp +node gsd-tools.cjs current-timestamp [full|date|filename] + +# Count and list pending todos +node gsd-tools.cjs list-todos [area] + +# Check file/directory existence +node gsd-tools.cjs verify-path-exists + +# Aggregate all SUMMARY.md data +node gsd-tools.cjs history-digest + +# Extract structured data from SUMMARY.md +node gsd-tools.cjs summary-extract [--fields field1,field2] + +# Project statistics +node gsd-tools.cjs stats [json|table] + +# Progress rendering +node gsd-tools.cjs progress [json|table|bar] + +# Complete a todo +node gsd-tools.cjs todo complete + +# UAT audit — scan all phases for unresolved items +node gsd-tools.cjs audit-uat + +# Git commit with config checks +node gsd-tools.cjs commit [--files f1 f2] [--amend] [--no-verify] +``` + +> **`--no-verify`**: Skips pre-commit hooks. Used by parallel executor agents during wave-based execution to avoid build lock contention (e.g., cargo lock fights in Rust projects). The orchestrator runs hooks once after each wave completes. Do not use `--no-verify` during sequential execution — let hooks run normally. + +# Web search (requires Brave API key) +node gsd-tools.cjs websearch [--limit N] [--freshness day|week|month] +``` + +--- + +## Module Architecture + +| Module | File | Exports | +|--------|------|---------| +| Core | `lib/core.cjs` | `error()`, `output()`, `parseArgs()`, shared utilities | +| State | `lib/state.cjs` | All `state` subcommands, `state-snapshot` | +| Phase | `lib/phase.cjs` | Phase CRUD, `find-phase`, `phase-plan-index`, `phases list` | +| Roadmap | `lib/roadmap.cjs` | Roadmap parsing, phase extraction, progress updates | +| Config | `lib/config.cjs` | Config read/write, section initialization | +| Verify | `lib/verify.cjs` | All verification and validation commands | +| Template | `lib/template.cjs` | Template selection and variable filling | +| Frontmatter | `lib/frontmatter.cjs` | YAML frontmatter CRUD | +| Init | `lib/init.cjs` | Compound context loading for all workflows | +| Milestone | `lib/milestone.cjs` | Milestone archival, requirements marking | +| Commands | `lib/commands.cjs` | Misc: slug, timestamp, todos, scaffold, stats, websearch | +| Model Profiles | `lib/model-profiles.cjs` | Profile resolution table | +| UAT | `lib/uat.cjs` | Cross-phase UAT/verification audit | +| Profile Output | `lib/profile-output.cjs` | Developer profile formatting | +| Profile Pipeline | `lib/profile-pipeline.cjs` | Session analysis pipeline | diff --git a/gsd-opencode/docs/COMMANDS.md b/gsd-opencode/docs/COMMANDS.md new file mode 100644 index 0000000..91719a0 --- /dev/null +++ b/gsd-opencode/docs/COMMANDS.md @@ -0,0 +1,933 @@ +# GSD Command Reference + +> Complete command syntax, flags, options, and examples. For feature details, see [Feature Reference](FEATURES.md). For workflow walkthroughs, see [User Guide](USER-GUIDE.md). + +--- + +## Command Syntax + +- **OpenCode / Gemini / Copilot:** `/gsd-command-name [args]` +- **OpenCode:** `/gsd-command-name [args]` +- **Codex:** `$gsd-command-name [args]` + +--- + +## Core Workflow Commands + +### `/gsd-new-project` + +Initialize a new project with deep context gathering. + +| Flag | Description | +|------|-------------| +| `--auto @file.md` | Auto-extract from document, skip interactive questions | + +**Prerequisites:** No existing `.planning/PROJECT.md` +**Produces:** `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, `config.json`, `research/`, `AGENTS.md` + +```bash +/gsd-new-project # Interactive mode +/gsd-new-project --auto @prd.md # Auto-extract from PRD +``` + +--- + +### `/gsd-new-workspace` + +Create an isolated workspace with repo copies and independent `.planning/` directory. + +| Flag | Description | +|------|-------------| +| `--name ` | Workspace name (required) | +| `--repos repo1,repo2` | Comma-separated repo paths or names | +| `--path /target` | Target directory (default: `~/gsd-workspaces/`) | +| `--strategy worktree\|clone` | Copy strategy (default: `worktree`) | +| `--branch ` | Branch to checkout (default: `workspace/`) | +| `--auto` | Skip interactive questions | + +**Use cases:** +- Multi-repo: work on a subset of repos with isolated GSD state +- Feature isolation: `--repos .` creates a worktree of the current repo + +**Produces:** `WORKSPACE.md`, `.planning/`, repo copies (worktrees or clones) + +```bash +/gsd-new-workspace --name feature-b --repos hr-ui,ZeymoAPI +/gsd-new-workspace --name feature-b --repos . --strategy worktree # Same-repo isolation +/gsd-new-workspace --name spike --repos api,web --strategy clone # Full clones +``` + +--- + +### `/gsd-list-workspaces` + +List active GSD workspaces and their status. + +**Scans:** `~/gsd-workspaces/` for `WORKSPACE.md` manifests +**Shows:** Name, repo count, strategy, GSD project status + +```bash +/gsd-list-workspaces +``` + +--- + +### `/gsd-remove-workspace` + +Remove a workspace and clean up git worktrees. + +| Argument | Required | Description | +|----------|----------|-------------| +| `` | Yes | Workspace name to remove | + +**Safety:** Refuses removal if any repo has uncommitted changes. Requires name confirmation. + +```bash +/gsd-remove-workspace feature-b +``` + +--- + +### `/gsd-discuss-phase` + +Capture implementation decisions before planning. + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | No | Phase number (defaults to current phase) | + +| Flag | Description | +|------|-------------| +| `--auto` | Auto-select recommended defaults for all questions | +| `--batch` | Group questions for batch intake instead of one-by-one | +| `--analyze` | Add trade-off analysis during discussion | + +**Prerequisites:** `.planning/ROADMAP.md` exists +**Produces:** `{phase}-CONTEXT.md`, `{phase}-DISCUSSION-LOG.md` (audit trail) + +```bash +/gsd-discuss-phase 1 # Interactive discussion for phase 1 +/gsd-discuss-phase 3 --auto # Auto-select defaults for phase 3 +/gsd-discuss-phase --batch # Batch mode for current phase +/gsd-discuss-phase 2 --analyze # Discussion with trade-off analysis +``` + +--- + +### `/gsd-ui-phase` + +Generate UI design contract for frontend phases. + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | No | Phase number (defaults to current phase) | + +**Prerequisites:** `.planning/ROADMAP.md` exists, phase has frontend/UI work +**Produces:** `{phase}-UI-SPEC.md` + +```bash +/gsd-ui-phase 2 # Design contract for phase 2 +``` + +--- + +### `/gsd-plan-phase` + +Research, plan, and verify a phase. + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | No | Phase number (defaults to next unplanned phase) | + +| Flag | Description | +|------|-------------| +| `--auto` | Skip interactive confirmations | +| `--research` | Force re-research even if RESEARCH.md exists | +| `--skip-research` | Skip domain research step | +| `--gaps` | Gap closure mode (reads VERIFICATION.md, skips research) | +| `--skip-verify` | Skip plan checker verification loop | +| `--prd ` | Use a PRD file instead of discuss-phase for context | +| `--reviews` | Replan with cross-AI review feedback from REVIEWS.md | + +**Prerequisites:** `.planning/ROADMAP.md` exists +**Produces:** `{phase}-RESEARCH.md`, `{phase}-{N}-PLAN.md`, `{phase}-VALIDATION.md` + +```bash +/gsd-plan-phase 1 # Research + plan + verify phase 1 +/gsd-plan-phase 3 --skip-research # Plan without research (familiar domain) +/gsd-plan-phase --auto # Non-interactive planning +``` + +--- + +### `/gsd-execute-phase` + +Execute all plans in a phase with wave-based parallelization, or run a specific wave. + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | **Yes** | Phase number to execute | +| `--wave N` | No | Execute only Wave `N` in the phase | + +**Prerequisites:** Phase has PLAN.md files +**Produces:** per-plan `{phase}-{N}-SUMMARY.md`, git commits, and `{phase}-VERIFICATION.md` when the phase is fully complete + +```bash +/gsd-execute-phase 1 # Execute phase 1 +/gsd-execute-phase 1 --wave 2 # Execute only Wave 2 +``` + +--- + +### `/gsd-verify-work` + +User acceptance testing with auto-diagnosis. + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | No | Phase number (defaults to last executed phase) | + +**Prerequisites:** Phase has been executed +**Produces:** `{phase}-UAT.md`, fix plans if issues found + +```bash +/gsd-verify-work 1 # UAT for phase 1 +``` + +--- + +### `/gsd-next` + +Automatically advance to the next logical workflow step. Reads project state and runs the appropriate command. + +**Prerequisites:** `.planning/` directory exists +**Behavior:** +- No project → suggests `/gsd-new-project` +- Phase needs discussion → runs `/gsd-discuss-phase` +- Phase needs planning → runs `/gsd-plan-phase` +- Phase needs execution → runs `/gsd-execute-phase` +- Phase needs verification → runs `/gsd-verify-work` +- All phases complete → suggests `/gsd-complete-milestone` + +```bash +/gsd-next # Auto-detect and run next step +``` + +--- + +### `/gsd-session-report` + +Generate a session report with work summary, outcomes, and estimated resource usage. + +**Prerequisites:** Active project with recent work +**Produces:** `.planning/reports/SESSION_REPORT.md` + +```bash +/gsd-session-report # Generate post-session summary +``` + +**Report includes:** +- Work performed (commits, plans executed, phases progressed) +- Outcomes and deliverables +- Blockers and decisions made +- Estimated token/cost usage +- Next steps recommendation + +--- + +### `/gsd-ship` + +Create PR from completed phase work with auto-generated body. + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | No | Phase number or milestone version (e.g., `4` or `v1.0`) | +| `--draft` | No | Create as draft PR | + +**Prerequisites:** Phase verified (`/gsd-verify-work` passed), `gh` CLI installed and authenticated +**Produces:** GitHub PR with rich body from planning artifacts, STATE.md updated + +```bash +/gsd-ship 4 # Ship phase 4 +/gsd-ship 4 --draft # Ship as draft PR +``` + +**PR body includes:** +- Phase goal from ROADMAP.md +- Changes summary from SUMMARY.md files +- Requirements addressed (REQ-IDs) +- Verification status +- Key decisions + +--- + +### `/gsd-ui-review` + +Retroactive 6-pillar visual audit of implemented frontend. + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | No | Phase number (defaults to last executed phase) | + +**Prerequisites:** Project has frontend code (works standalone, no GSD project needed) +**Produces:** `{phase}-UI-REVIEW.md`, screenshots in `.planning/ui-reviews/` + +```bash +/gsd-ui-review # Audit current phase +/gsd-ui-review 3 # Audit phase 3 +``` + +--- + +### `/gsd-audit-uat` + +Cross-phase audit of all outstanding UAT and verification items. + +**Prerequisites:** At least one phase has been executed with UAT or verification +**Produces:** Categorized audit report with human test plan + +```bash +/gsd-audit-uat +``` + +--- + +### `/gsd-audit-milestone` + +Verify milestone met its definition of done. + +**Prerequisites:** All phases executed +**Produces:** Audit report with gap analysis + +```bash +/gsd-audit-milestone +``` + +--- + +### `/gsd-complete-milestone` + +Archive milestone, tag release. + +**Prerequisites:** Milestone audit complete (recommended) +**Produces:** `MILESTONES.md` entry, git tag + +```bash +/gsd-complete-milestone +``` + +--- + +### `/gsd-milestone-summary` + +Generate comprehensive project summary from milestone artifacts for team onboarding and review. + +| Argument | Required | Description | +|----------|----------|-------------| +| `version` | No | Milestone version (defaults to current/latest milestone) | + +**Prerequisites:** At least one completed or in-progress milestone +**Produces:** `.planning/reports/MILESTONE_SUMMARY-v{version}.md` + +**Summary includes:** +- Overview, architecture decisions, phase-by-phase breakdown +- Key decisions and trade-offs +- Requirements coverage +- Tech debt and deferred items +- Getting started guide for new team members +- Interactive Q&A offered after generation + +```bash +/gsd-milestone-summary # Summarize current milestone +/gsd-milestone-summary v1.0 # Summarize specific milestone +``` + +--- + +### `/gsd-new-milestone` + +Start next version cycle. + +| Argument | Required | Description | +|----------|----------|-------------| +| `name` | No | Milestone name | +| `--reset-phase-numbers` | No | Restart the new milestone at Phase 1 and archive old phase dirs before roadmapping | + +**Prerequisites:** Previous milestone completed +**Produces:** Updated `PROJECT.md`, new `REQUIREMENTS.md`, new `ROADMAP.md` + +```bash +/gsd-new-milestone # Interactive +/gsd-new-milestone "v2.0 Mobile" # Named milestone +/gsd-new-milestone --reset-phase-numbers "v2.0 Mobile" # Restart milestone numbering at 1 +``` + +--- + +## Phase Management Commands + +### `/gsd-add-phase` + +Append new phase to roadmap. + +```bash +/gsd-add-phase # Interactive — describe the phase +``` + +### `/gsd-insert-phase` + +Insert urgent work between phases using decimal numbering. + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | No | Insert after this phase number | + +```bash +/gsd-insert-phase 3 # Insert between phase 3 and 4 → creates 3.1 +``` + +### `/gsd-remove-phase` + +Remove future phase and renumber subsequent phases. + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | No | Phase number to remove | + +```bash +/gsd-remove-phase 7 # Remove phase 7, renumber 8→7, 9→8, etc. +``` + +### `/gsd-list-phase-assumptions` + +Preview OpenCode's intended approach before planning. + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | No | Phase number | + +```bash +/gsd-list-phase-assumptions 2 # See assumptions for phase 2 +``` + +### `/gsd-plan-milestone-gaps` + +Create phases to close gaps from milestone audit. + +```bash +/gsd-plan-milestone-gaps # Creates phases for each audit gap +``` + +### `/gsd-research-phase` + +Deep ecosystem research only (standalone — usually use `/gsd-plan-phase` instead). + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | No | Phase number | + +```bash +/gsd-research-phase 4 # Research phase 4 domain +``` + +### `/gsd-validate-phase` + +Retroactively audit and fill Nyquist validation gaps. + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | No | Phase number | + +```bash +/gsd-validate-phase 2 # Audit test coverage for phase 2 +``` + +--- + +## Navigation Commands + +### `/gsd-progress` + +Show status and next steps. + +```bash +/gsd-progress # "Where am I? What's next?" +``` + +### `/gsd-resume-work` + +Restore full context from last session. + +```bash +/gsd-resume-work # After context reset or new session +``` + +### `/gsd-pause-work` + +Save context handoff when stopping mid-phase. + +```bash +/gsd-pause-work # Creates continue-here.md +``` + +### `/gsd-manager` + +Interactive command center for managing multiple phases from one terminal. + +**Prerequisites:** `.planning/ROADMAP.md` exists +**Behavior:** +- Dashboard of all phases with visual status indicators +- Recommends optimal next actions based on dependencies and progress +- Dispatches work: discuss runs inline, plan/execute run as background agents +- Designed for power users parallelizing work across phases from one terminal + +```bash +/gsd-manager # Open command center dashboard +``` + +--- + +### `/gsd-help` + +Show all commands and usage guide. + +```bash +/gsd-help # Quick reference +``` + +--- + +## Utility Commands + +### `/gsd-quick` + +Execute ad-hoc task with GSD guarantees. + +| Flag | Description | +|------|-------------| +| `--full` | Enable plan checking (2 iterations) + post-execution verification | +| `--discuss` | Lightweight pre-planning discussion | +| `--research` | Spawn focused researcher before planning | + +Flags are composable. + +```bash +/gsd-quick # Basic quick task +/gsd-quick --discuss --research # Discussion + research + planning +/gsd-quick --full # With plan checking and verification +/gsd-quick --discuss --research --full # All optional stages +``` + +### `/gsd-autonomous` + +Run all remaining phases autonomously. + +| Flag | Description | +|------|-------------| +| `--from N` | Start from a specific phase number | + +```bash +/gsd-autonomous # Run all remaining phases +/gsd-autonomous --from 3 # Start from phase 3 +``` + +### `/gsd-do` + +Route freeform text to the right GSD command. + +```bash +/gsd-do # Then describe what you want +``` + +### `/gsd-note` + +Zero-friction idea capture — append, list, or promote notes to todos. + +| Argument | Required | Description | +|----------|----------|-------------| +| `text` | No | Note text to capture (default: append mode) | +| `list` | No | List all notes from project and global scopes | +| `promote N` | No | Convert note N into a structured todo | + +| Flag | Description | +|------|-------------| +| `--global` | Use global scope for note operations | + +```bash +/gsd-note "Consider caching strategy for API responses" +/gsd-note list +/gsd-note promote 3 +``` + +### `/gsd-debug` + +Systematic debugging with persistent state. + +| Argument | Required | Description | +|----------|----------|-------------| +| `description` | No | Description of the bug | + +```bash +/gsd-debug "Login button not responding on mobile Safari" +``` + +### `/gsd-add-todo` + +Capture idea or task for later. + +| Argument | Required | Description | +|----------|----------|-------------| +| `description` | No | Todo description | + +```bash +/gsd-add-todo "Consider adding dark mode support" +``` + +### `/gsd-check-todos` + +List pending todos and select one to work on. + +```bash +/gsd-check-todos +``` + +### `/gsd-add-tests` + +Generate tests for a completed phase. + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | No | Phase number | + +```bash +/gsd-add-tests 2 # Generate tests for phase 2 +``` + +### `/gsd-stats` + +Display project statistics. + +```bash +/gsd-stats # Project metrics dashboard +``` + +### `/gsd-profile-user` + +Generate a developer behavioral profile from OpenCode session analysis across 8 dimensions (communication style, decision patterns, debugging approach, UX preferences, vendor choices, frustration triggers, learning style, explanation depth). Produces artifacts that personalize OpenCode's responses. + +| Flag | Description | +|------|-------------| +| `--questionnaire` | Use interactive questionnaire instead of session analysis | +| `--refresh` | Re-analyze sessions and regenerate profile | + +**Generated artifacts:** +- `USER-PROFILE.md` — Full behavioral profile +- `/gsd-dev-preferences` command — Load preferences in any session +- `AGENTS.md` profile section — Auto-discovered by OpenCode + +```bash +/gsd-profile-user # Analyze sessions and build profile +/gsd-profile-user --questionnaire # Interactive questionnaire fallback +/gsd-profile-user --refresh # Re-generate from fresh analysis +``` + +### `/gsd-health` + +Validate `.planning/` directory integrity. + +| Flag | Description | +|------|-------------| +| `--repair` | Auto-fix recoverable issues | + +```bash +/gsd-health # Check integrity +/gsd-health --repair # Check and fix +``` + +### `/gsd-cleanup` + +Archive accumulated phase directories from completed milestones. + +```bash +/gsd-cleanup +``` + +--- + +## Diagnostics Commands + +### `/gsd-forensics` + +Post-mortem investigation of failed or stuck GSD workflows. + +| Argument | Required | Description | +|----------|----------|-------------| +| `description` | No | Problem description (prompted if omitted) | + +**Prerequisites:** `.planning/` directory exists +**Produces:** `.planning/forensics/report-{timestamp}.md` + +**Investigation covers:** +- Git history analysis (recent commits, stuck patterns, time gaps) +- Artifact integrity (expected files for completed phases) +- STATE.md anomalies and session history +- Uncommitted work, conflicts, abandoned changes +- At least 4 anomaly types checked (stuck loop, missing artifacts, abandoned work, crash/interruption) +- GitHub issue creation offered if actionable findings exist + +```bash +/gsd-forensics # Interactive — prompted for problem +/gsd-forensics "Phase 3 execution stalled" # With problem description +``` + +--- + +## Workstream Management + +### `/gsd-workstreams` + +Manage parallel workstreams for concurrent work on different milestone areas. + +**Subcommands:** + +| Subcommand | Description | +|------------|-------------| +| `list` | List all workstreams with status (default if no subcommand) | +| `create ` | Create a new workstream | +| `status ` | Detailed status for one workstream | +| `switch ` | Set active workstream | +| `progress` | Progress summary across all workstreams | +| `complete ` | Archive a completed workstream | +| `resume ` | Resume work in a workstream | + +**Prerequisites:** Active GSD project +**Produces:** Workstream directories under `.planning/`, state tracking per workstream + +```bash +/gsd-workstreams # List all workstreams +/gsd-workstreams create backend-api # Create new workstream +/gsd-workstreams switch backend-api # Set active workstream +/gsd-workstreams status backend-api # Detailed status +/gsd-workstreams progress # Cross-workstream progress overview +/gsd-workstreams complete backend-api # Archive completed workstream +/gsd-workstreams resume backend-api # Resume work in workstream +``` + +--- + +## Configuration Commands + +### `/gsd-settings` + +Interactive configuration of workflow toggles and model profile. + +```bash +/gsd-settings # Interactive config +``` + +### `/gsd-set-profile` + +Quick profile switch. + +| Argument | Required | Description | +|----------|----------|-------------| +| `profile` | **Yes** | `quality`, `balanced`, `budget`, or `inherit` | + +```bash +/gsd-set-profile budget # Switch to budget profile +/gsd-set-profile quality # Switch to quality profile +``` + +--- + +## Brownfield Commands + +### `/gsd-map-codebase` + +Analyze existing codebase with parallel mapper agents. + +| Argument | Required | Description | +|----------|----------|-------------| +| `area` | No | Scope mapping to a specific area | + +```bash +/gsd-map-codebase # Full codebase analysis +/gsd-map-codebase auth # Focus on auth area +``` + +--- + +## Update Commands + +### `/gsd-update` + +Update GSD with changelog preview. + +```bash +/gsd-update # Check for updates and install +``` + +### `/gsd-reapply-patches` + +Restore local modifications after a GSD update. + +```bash +/gsd-reapply-patches # Merge back local changes +``` + +--- + +## Fast & Inline Commands + +### `/gsd-fast` + +Execute a trivial task inline — no subagents, no planning overhead. For typo fixes, config changes, small refactors, forgotten commits. + +| Argument | Required | Description | +|----------|----------|-------------| +| `task description` | No | What to do (prompted if omitted) | + +**Not a replacement for `/gsd-quick`** — use `/gsd-quick` for anything needing research, multi-step planning, or verification. + +```bash +/gsd-fast "fix typo in README" +/gsd-fast "add .env to gitignore" +``` + +--- + +## Code Quality Commands + +### `/gsd-review` + +Cross-AI peer review of phase plans from external AI CLIs. + +| Argument | Required | Description | +|----------|----------|-------------| +| `--phase N` | **Yes** | Phase number to review | + +| Flag | Description | +|------|-------------| +| `--gemini` | Include Gemini CLI review | +| `--OpenCode` | Include OpenCode CLI review (separate session) | +| `--codex` | Include Codex CLI review | +| `--all` | Include all available CLIs | + +**Produces:** `{phase}-REVIEWS.md` — consumable by `/gsd-plan-phase --reviews` + +```bash +/gsd-review --phase 3 --all +/gsd-review --phase 2 --gemini +``` + +--- + +### `/gsd-pr-branch` + +Create a clean PR branch by filtering out `.planning/` commits. + +| Argument | Required | Description | +|----------|----------|-------------| +| `target branch` | No | Base branch (default: `main`) | + +**Purpose:** Reviewers see only code changes, not GSD planning artifacts. + +```bash +/gsd-pr-branch # Filter against main +/gsd-pr-branch develop # Filter against develop +``` + +--- + +### `/gsd-audit-uat` + +Cross-phase audit of all outstanding UAT and verification items. + +**Prerequisites:** At least one phase has been executed with UAT or verification +**Produces:** Categorized audit report with human test plan + +```bash +/gsd-audit-uat +``` + +--- + +## Backlog & Thread Commands + +### `/gsd-add-backlog` + +Add an idea to the backlog parking lot using 999.x numbering. + +| Argument | Required | Description | +|----------|----------|-------------| +| `description` | **Yes** | Backlog item description | + +**999.x numbering** keeps backlog items outside the active phase sequence. Phase directories are created immediately so `/gsd-discuss-phase` and `/gsd-plan-phase` work on them. + +```bash +/gsd-add-backlog "GraphQL API layer" +/gsd-add-backlog "Mobile responsive redesign" +``` + +--- + +### `/gsd-review-backlog` + +Review and promote backlog items to active milestone. + +**Actions per item:** Promote (move to active sequence), Keep (leave in backlog), Remove (delete). + +```bash +/gsd-review-backlog +``` + +--- + +### `/gsd-plant-seed` + +Capture a forward-looking idea with trigger conditions — surfaces automatically at the right milestone. + +| Argument | Required | Description | +|----------|----------|-------------| +| `idea summary` | No | Seed description (prompted if omitted) | + +Seeds solve context rot: instead of a one-liner in Deferred that nobody reads, a seed preserves the full WHY, WHEN to surface, and breadcrumbs to details. + +**Produces:** `.planning/seeds/SEED-NNN-slug.md` +**Consumed by:** `/gsd-new-milestone` (scans seeds and presents matches) + +```bash +/gsd-plant-seed "Add real-time collaboration when WebSocket infra is in place" +``` + +--- + +### `/gsd-thread` + +Manage persistent context threads for cross-session work. + +| Argument | Required | Description | +|----------|----------|-------------| +| (none) | — | List all threads | +| `name` | — | Resume existing thread by name | +| `description` | — | Create new thread | + +Threads are lightweight cross-session knowledge stores for work that spans multiple sessions but doesn't belong to any specific phase. Lighter weight than `/gsd-pause-work`. + +```bash +/gsd-thread # List all threads +/gsd-thread fix-deploy-key-auth # Resume thread +/gsd-thread "Investigate TCP timeout in pasta service" # Create new +``` + +--- + +## Community Commands + +### `/gsd-join-discord` + +Open Discord community invite. + +```bash +/gsd-join-discord +``` diff --git a/gsd-opencode/docs/CONFIGURATION.md b/gsd-opencode/docs/CONFIGURATION.md new file mode 100644 index 0000000..de0683d --- /dev/null +++ b/gsd-opencode/docs/CONFIGURATION.md @@ -0,0 +1,409 @@ +# GSD Configuration Reference + +> Full configuration schema, workflow toggles, model profiles, and git branching options. For feature context, see [Feature Reference](FEATURES.md). + +--- + +## Configuration File + +GSD stores project settings in `.planning/config.json`. Created during `/gsd-new-project`, updated via `/gsd-settings`. + +### Full Schema + +```json +{ + "mode": "interactive", + "granularity": "standard", + "model_profile": "balanced", + "model_overrides": {}, + "planning": { + "commit_docs": true, + "search_gitignored": false + }, + "workflow": { + "research": true, + "plan_check": true, + "verifier": true, + "auto_advance": false, + "nyquist_validation": true, + "ui_phase": true, + "ui_safety_gate": true, + "node_repair": true, + "node_repair_budget": 2, + "research_before_questions": false, + "discuss_mode": "discuss", + "skip_discuss": false, + "text_mode": false + }, + "hooks": { + "context_warnings": true, + "workflow_guard": false + }, + "parallelization": { + "enabled": true, + "plan_level": true, + "task_level": false, + "skip_checkpoints": true, + "max_concurrent_agents": 3, + "min_plans_for_parallel": 2 + }, + "git": { + "branching_strategy": "none", + "phase_branch_template": "gsd/phase-{phase}-{slug}", + "milestone_branch_template": "gsd/{milestone}-{slug}", + "quick_branch_template": null + }, + "gates": { + "confirm_project": true, + "confirm_phases": true, + "confirm_roadmap": true, + "confirm_breakdown": true, + "confirm_plan": true, + "execute_next_plan": true, + "issues_review": true, + "confirm_transition": true + }, + "safety": { + "always_confirm_destructive": true, + "always_confirm_external_services": true + }, + "agent_skills": {} +} +``` + +--- + +## Core Settings + +| Setting | Type | Options | Default | Description | +|---------|------|---------|---------|-------------| +| `mode` | enum | `interactive`, `yolo` | `interactive` | `yolo` auto-approves decisions; `interactive` confirms at each step | +| `granularity` | enum | `coarse`, `standard`, `fine` | `standard` | Controls phase count: `coarse` (3-5), `standard` (5-8), `fine` (8-12) | +| `model_profile` | enum | `quality`, `balanced`, `budget`, `inherit` | `balanced` | Model tier for each agent (see [Model Profiles](#model-profiles)) | + +> **Note:** `granularity` was renamed from `depth` in v1.22.3. Existing configs are auto-migrated. + +--- + +## Workflow Toggles + +All workflow toggles follow the **absent = enabled** pattern. If a key is missing from config, it defaults to `true`. + +| Setting | Type | Default | Description | +|---------|------|---------|-------------| +| `workflow.research` | boolean | `true` | Domain investigation before planning each phase | +| `workflow.plan_check` | boolean | `true` | Plan verification loop (up to 3 iterations) | +| `workflow.verifier` | boolean | `true` | Post-execution verification against phase goals | +| `workflow.auto_advance` | boolean | `false` | Auto-chain discuss → plan → execute without stopping | +| `workflow.nyquist_validation` | boolean | `true` | Test coverage mapping during plan-phase research | +| `workflow.ui_phase` | boolean | `true` | Generate UI design contracts for frontend phases | +| `workflow.ui_safety_gate` | boolean | `true` | Prompt to run /gsd-ui-phase for frontend phases during plan-phase | +| `workflow.node_repair` | boolean | `true` | Autonomous task repair on verification failure | +| `workflow.node_repair_budget` | number | `2` | Max repair attempts per failed task | +| `workflow.research_before_questions` | boolean | `false` | Run research before discussion questions instead of after | +| `workflow.discuss_mode` | string | `'discuss'` | Controls how `/gsd-discuss-phase` gathers context. `'discuss'` (default) asks questions one-by-one. `'assumptions'` reads the codebase first, generates structured assumptions with confidence levels, and only asks you to correct what's wrong. Added in v1.28 | +| `workflow.skip_discuss` | boolean | `false` | When `true`, `/gsd-autonomous` bypasses the discuss-phase entirely, writing minimal CONTEXT.md from the ROADMAP phase goal. Useful for projects where developer preferences are fully captured in PROJECT.md/REQUIREMENTS.md. Added in v1.28 | +| `workflow.text_mode` | boolean | `false` | Replaces question TUI menus with plain-text numbered lists. Required for OpenCode remote sessions (`/rc` mode) where TUI menus don't render. Can also be set per-session with `--text` flag on discuss-phase. Added in v1.28 | + +### Recommended Presets + +| Scenario | mode | granularity | profile | research | plan_check | verifier | +|----------|------|-------------|---------|----------|------------|----------| +| Prototyping | `yolo` | `coarse` | `budget` | `false` | `false` | `false` | +| Normal development | `interactive` | `standard` | `balanced` | `true` | `true` | `true` | +| Production release | `interactive` | `fine` | `quality` | `true` | `true` | `true` | + +--- + +## Planning Settings + +| Setting | Type | Default | Description | +|---------|------|---------|-------------| +| `planning.commit_docs` | boolean | `true` | Whether `.planning/` files are committed to git | +| `planning.search_gitignored` | boolean | `false` | Add `--no-ignore` to broad searches to include `.planning/` | + +### Auto-Detection + +If `.planning/` is in `.gitignore`, `commit_docs` is automatically `false` regardless of config.json. This prevents git errors. + +--- + +## Hook Settings + +| Setting | Type | Default | Description | +|---------|------|---------|-------------| +| `hooks.context_warnings` | boolean | `true` | Show context window usage warnings via context monitor hook | +| `hooks.workflow_guard` | boolean | `false` | Warn when file edits happen outside GSD workflow context (advises using `/gsd-quick` or `/gsd-fast`) | + +The prompt injection guard hook (`gsd-prompt-guard.js`) is always active and cannot be disabled — it's a security feature, not a workflow toggle. + +### Private Planning Setup + +To keep planning artifacts out of git: + +1. Set `planning.commit_docs: false` and `planning.search_gitignored: true` +2. Add `.planning/` to `.gitignore` +3. If previously tracked: `git rm -r --cached .planning/ && git commit -m "chore: stop tracking planning docs"` + +--- + +## Agent Skills Injection + +Inject custom skill files into GSD subagent prompts. Skills are read by agents at spawn time, giving them project-specific instructions beyond what AGENTS.md provides. + +| Setting | Type | Default | Description | +|---------|------|---------|-------------| +| `agent_skills` | object | `{}` | Map of agent types to skill directory paths | + +### Configuration + +Add an `agent_skills` section to `.planning/config.json` mapping agent types to arrays of skill directory paths (relative to project root): + +```json +{ + "agent_skills": { + "gsd-executor": ["skills/testing-standards", "skills/api-conventions"], + "gsd-planner": ["skills/architecture-rules"], + "gsd-verifier": ["skills/acceptance-criteria"] + } +} +``` + +Each path must be a directory containing a `SKILL.md` file. Paths are validated for safety (no traversal outside project root). + +### Supported Agent Types + +Any GSD agent type can receive skills. Common types: + +- `gsd-executor` -- executes implementation plans +- `gsd-planner` -- creates phase plans +- `gsd-checker` -- verifies plan quality +- `gsd-verifier` -- post-execution verification +- `gsd-researcher` -- phase research +- `gsd-project-researcher` -- new-project research +- `gsd-debugger` -- diagnostic agents +- `gsd-codebase-mapper` -- codebase analysis +- `gsd-advisor` -- discuss-phase advisors +- `gsd-ui-researcher` -- UI design contract creation +- `gsd-ui-checker` -- UI spec verification +- `gsd-roadmapper` -- roadmap creation +- `gsd-synthesizer` -- research synthesis + +### How It Works + +At spawn time, workflows call `node gsd-tools.cjs agent-skills ` to load configured skills. If skills exist for the agent type, they are injected as an `` block in the task() prompt: + +```xml + +read these user-configured skills: +- @skills/testing-standards/SKILL.md +- @skills/api-conventions/SKILL.md + +``` + +If no skills are configured, the block is omitted (zero overhead). + +### CLI + +Set skills via the CLI: + +```bash +node gsd-tools.cjs config-set agent_skills.gsd-executor '["skills/my-skill"]' +``` + +--- + +## Parallelization Settings + +| Setting | Type | Default | Description | +|---------|------|---------|-------------| +| `parallelization.enabled` | boolean | `true` | Run independent plans simultaneously | +| `parallelization.plan_level` | boolean | `true` | Parallelize at plan level | +| `parallelization.task_level` | boolean | `false` | Parallelize tasks within a plan | +| `parallelization.skip_checkpoints` | boolean | `true` | Skip checkpoints during parallel execution | +| `parallelization.max_concurrent_agents` | number | `3` | Maximum simultaneous agents | +| `parallelization.min_plans_for_parallel` | number | `2` | Minimum plans to trigger parallel execution | + +> **Pre-commit hooks and parallel execution**: When parallelization is enabled, executor agents commit with `--no-verify` to avoid build lock contention (e.g., cargo lock fights in Rust projects). The orchestrator validates hooks once after each wave completes. STATE.md writes are protected by file-level locking to prevent concurrent write corruption. If you need hooks to run per-commit, set `parallelization.enabled: false`. + +--- + +## Git Branching + +| Setting | Type | Default | Description | +|---------|------|---------|-------------| +| `git.branching_strategy` | enum | `none` | `none`, `phase`, or `milestone` | +| `git.phase_branch_template` | string | `gsd/phase-{phase}-{slug}` | Branch name template for phase strategy | +| `git.milestone_branch_template` | string | `gsd/{milestone}-{slug}` | Branch name template for milestone strategy | +| `git.quick_branch_template` | string or null | `null` | Optional branch name template for `/gsd-quick` tasks | + +### Strategy Comparison + +| Strategy | Creates Branch | Scope | Merge Point | Best For | +|----------|---------------|-------|-------------|----------| +| `none` | Never | N/A | N/A | Solo development, simple projects | +| `phase` | At `execute-phase` start | One phase | User merges after phase | Code review per phase, granular rollback | +| `milestone` | At first `execute-phase` | All phases in milestone | At `complete-milestone` | Release branches, PR per version | + +### Template Variables + +| Variable | Available In | Example | +|----------|-------------|---------| +| `{phase}` | `phase_branch_template` | `03` (zero-padded) | +| `{slug}` | Both templates | `user-authentication` (lowercase, hyphenated) | +| `{milestone}` | `milestone_branch_template` | `v1.0` | +| `{num}` / `{quick}` | `quick_branch_template` | `260317-abc` (quick task ID) | + +Example quick-task branching: + +```json +"git": { + "quick_branch_template": "gsd/quick-{num}-{slug}" +} +``` + +### Merge Options at Milestone Completion + +| Option | Git Command | Result | +|--------|-------------|--------| +| Squash merge (recommended) | `git merge --squash` | Single clean commit per branch | +| Merge with history | `git merge --no-ff` | Preserves all individual commits | +| Delete without merging | `git branch -D` | Discard branch work | +| Keep branches | (none) | Manual handling later | + +--- + +## Gate Settings + +Control confirmation prompts during workflows. + +| Setting | Type | Default | Description | +|---------|------|---------|-------------| +| `gates.confirm_project` | boolean | `true` | Confirm project details before finalizing | +| `gates.confirm_phases` | boolean | `true` | Confirm phase breakdown | +| `gates.confirm_roadmap` | boolean | `true` | Confirm roadmap before proceeding | +| `gates.confirm_breakdown` | boolean | `true` | Confirm task breakdown | +| `gates.confirm_plan` | boolean | `true` | Confirm each plan before execution | +| `gates.execute_next_plan` | boolean | `true` | Confirm before executing next plan | +| `gates.issues_review` | boolean | `true` | Review issues before creating fix plans | +| `gates.confirm_transition` | boolean | `true` | Confirm phase transition | + +--- + +## Safety Settings + +| Setting | Type | Default | Description | +|---------|------|---------|-------------| +| `safety.always_confirm_destructive` | boolean | `true` | Confirm destructive operations (deletes, overwrites) | +| `safety.always_confirm_external_services` | boolean | `true` | Confirm external service interactions | + +--- + +## Hook Settings + +| Setting | Type | Default | Description | +|---------|------|---------|-------------| +| `hooks.context_warnings` | boolean | `true` | Show context window usage warnings during sessions | + +--- + +## Model Profiles + +### Profile Definitions + +| Agent | `quality` | `balanced` | `budget` | `inherit` | +|-------|-----------|------------|----------|-----------| +| gsd-planner | Opus | Opus | Sonnet | Inherit | +| gsd-roadmapper | Opus | Sonnet | Sonnet | Inherit | +| gsd-executor | Opus | Sonnet | Sonnet | Inherit | +| gsd-phase-researcher | Opus | Sonnet | Haiku | Inherit | +| gsd-project-researcher | Opus | Sonnet | Haiku | Inherit | +| gsd-research-synthesizer | Sonnet | Sonnet | Haiku | Inherit | +| gsd-debugger | Opus | Sonnet | Sonnet | Inherit | +| gsd-codebase-mapper | Sonnet | Haiku | Haiku | Inherit | +| gsd-verifier | Sonnet | Sonnet | Haiku | Inherit | +| gsd-plan-checker | Sonnet | Sonnet | Haiku | Inherit | +| gsd-integration-checker | Sonnet | Sonnet | Haiku | Inherit | +| gsd-nyquist-auditor | Sonnet | Sonnet | Haiku | Inherit | + +### Per-Agent Overrides + +Override specific agents without changing the entire profile: + +```json +{ + "model_profile": "balanced", + "model_overrides": { + "gsd-executor": "opus", + "gsd-planner": "haiku" + } +} +``` + +Valid override values: `opus`, `sonnet`, `haiku`, `inherit`, or any fully-qualified model ID (e.g., `"openai/o3"`, `"google/gemini-2.5-pro"`). + +### Non-OpenCode Runtimes (Codex, OpenCode, Gemini CLI) + +When GSD is installed for a non-OpenCode runtime, the installer automatically sets `resolve_model_ids: "omit"` in `~/.gsd/defaults.json`. This causes GSD to return an empty model parameter for all agents, so each agent uses whatever model the runtime is configured with. No additional setup is needed for the default case. + +If you want different agents to use different models, use `model_overrides` with fully-qualified model IDs that your runtime recognizes: + +```json +{ + "resolve_model_ids": "omit", + "model_overrides": { + "gsd-planner": "o3", + "gsd-executor": "o4-mini", + "gsd-debugger": "o3", + "gsd-codebase-mapper": "o4-mini" + } +} +``` + +The intent is the same as the OpenCode profile tiers -- use a stronger model for planning and debugging (where reasoning quality matters most), and a cheaper model for execution and mapping (where the plan already contains the reasoning). + +**When to use which approach:** + +| Scenario | Setting | Effect | +|----------|---------|--------| +| Non-OpenCode runtime, single model | `resolve_model_ids: "omit"` (installer default) | All agents use the runtime's default model | +| Non-OpenCode runtime, tiered models | `resolve_model_ids: "omit"` + `model_overrides` | Named agents use specific models, others use runtime default | +| OpenCode with OpenRouter/local provider | `model_profile: "inherit"` | All agents follow the session model | +| OpenCode with OpenRouter, tiered | `model_profile: "inherit"` + `model_overrides` | Named agents use specific models, others inherit | + +**`resolve_model_ids` values:** + +| Value | Behavior | Use When | +|-------|----------|----------| +| `false` (default) | Returns OpenCode aliases (`opus`, `sonnet`, `haiku`) | OpenCode with native Anthropic API | +| `true` | Maps aliases to full OpenCode model IDs (`OpenCode-opus-4-0`) | OpenCode with API that requires full IDs | +| `"omit"` | Returns empty string (runtime picks its default) | Non-OpenCode runtimes (Codex, OpenCode, Gemini CLI) | + +### Profile Philosophy + +| Profile | Philosophy | When to Use | +|---------|-----------|-------------| +| `quality` | Opus for all decision-making, Sonnet for verification | Quota available, critical architecture work | +| `balanced` | Opus for planning only, Sonnet for everything else | Normal development (default) | +| `budget` | Sonnet for code-writing, Haiku for research/verification | High-volume work, less critical phases | +| `inherit` | All agents use current session model | Dynamic model switching, **non-Anthropic providers** (OpenRouter, local models) | + +--- + +## Environment Variables + +| Variable | Purpose | +|----------|---------| +| `CLAUDE_CONFIG_DIR` | Override default config directory (`$HOME/.config/opencode/`) | +| `GEMINI_API_KEY` | Detected by context monitor to switch hook event name | +| `WSL_DISTRO_NAME` | Detected by installer for WSL path handling | + +--- + +## Global Defaults + +Save settings as global defaults for future projects: + +**Location:** `~/.gsd/defaults.json` + +When `/gsd-new-project` creates a new `config.json`, it reads global defaults and merges them as the starting configuration. Per-project settings always override globals. diff --git a/gsd-opencode/docs/FEATURES.md b/gsd-opencode/docs/FEATURES.md new file mode 100644 index 0000000..244655f --- /dev/null +++ b/gsd-opencode/docs/FEATURES.md @@ -0,0 +1,1290 @@ +# GSD Feature Reference + +> Complete feature and function documentation with requirements. For architecture details, see [Architecture](ARCHITECTURE.md). For command syntax, see [Command Reference](COMMANDS.md). + +--- + +## Table of Contents + +- [Core Features](#core-features) + - [Project Initialization](#1-project-initialization) + - [Phase Discussion](#2-phase-discussion) + - [UI Design Contract](#3-ui-design-contract) + - [Phase Planning](#4-phase-planning) + - [Phase Execution](#5-phase-execution) + - [Work Verification](#6-work-verification) + - [UI Review](#7-ui-review) + - [Milestone Management](#8-milestone-management) +- [Planning Features](#planning-features) + - [Phase Management](#9-phase-management) + - [Quick Mode](#10-quick-mode) + - [Autonomous Mode](#11-autonomous-mode) + - [Freeform Routing](#12-freeform-routing) + - [Note Capture](#13-note-capture) + - [Auto-Advance (Next)](#14-auto-advance-next) +- [Quality Assurance Features](#quality-assurance-features) + - [Nyquist Validation](#15-nyquist-validation) + - [Plan Checking](#16-plan-checking) + - [Post-Execution Verification](#17-post-execution-verification) + - [Node Repair](#18-node-repair) + - [Health Validation](#19-health-validation) + - [Cross-Phase Regression Gate](#20-cross-phase-regression-gate) + - [Requirements Coverage Gate](#21-requirements-coverage-gate) +- [Context Engineering Features](#context-engineering-features) + - [Context Window Monitoring](#22-context-window-monitoring) + - [Session Management](#23-session-management) + - [Session Reporting](#24-session-reporting) + - [Multi-Agent Orchestration](#25-multi-agent-orchestration) + - [Model Profiles](#26-model-profiles) +- [Brownfield Features](#brownfield-features) + - [Codebase Mapping](#27-codebase-mapping) +- [Utility Features](#utility-features) + - [Debug System](#28-debug-system) + - [Todo Management](#29-todo-management) + - [Statistics Dashboard](#30-statistics-dashboard) + - [Update System](#31-update-system) + - [Settings Management](#32-settings-management) + - [Test Generation](#33-test-generation) +- [Infrastructure Features](#infrastructure-features) + - [Git Integration](#34-git-integration) + - [CLI Tools](#35-cli-tools) + - [Multi-Runtime Support](#36-multi-runtime-support) + - [Hook System](#37-hook-system) + - [Developer Profiling](#38-developer-profiling) + - [Execution Hardening](#39-execution-hardening) + - [Verification Debt Tracking](#40-verification-debt-tracking) +- [v1.27 Features](#v127-features) + - [Fast Mode](#41-fast-mode) + - [Cross-AI Peer Review](#42-cross-ai-peer-review) + - [Backlog Parking Lot](#43-backlog-parking-lot) + - [Persistent Context Threads](#44-persistent-context-threads) + - [PR Branch Filtering](#45-pr-branch-filtering) + - [Security Hardening](#46-security-hardening) + - [Multi-Repo Workspace Support](#47-multi-repo-workspace-support) + - [Discussion Audit Trail](#48-discussion-audit-trail) +- [v1.28 Features](#v128-features) + - [Forensics](#49-forensics) + - [Milestone Summary](#50-milestone-summary) + - [Workstream Namespacing](#51-workstream-namespacing) + - [Manager Dashboard](#52-manager-dashboard) + - [Assumptions Discussion Mode](#53-assumptions-discussion-mode) + - [UI Phase Auto-Detection](#54-ui-phase-auto-detection) + - [Multi-Runtime Installer Selection](#55-multi-runtime-installer-selection) + +--- + +## Core Features + +### 1. Project Initialization + +**Command:** `/gsd-new-project [--auto @file.md]` + +**Purpose:** Transform a user's idea into a fully structured project with research, scoped requirements, and a phased roadmap. + +**Requirements:** +- REQ-INIT-01: System MUST conduct adaptive questioning until project scope is fully understood +- REQ-INIT-02: System MUST spawn parallel research agents to investigate the domain ecosystem +- REQ-INIT-03: System MUST extract requirements into v1 (must-have), v2 (future), and out-of-scope categories +- REQ-INIT-04: System MUST generate a phased roadmap with requirement traceability +- REQ-INIT-05: System MUST require user approval of the roadmap before proceeding +- REQ-INIT-06: System MUST prevent re-initialization when `.planning/PROJECT.md` already exists +- REQ-INIT-07: System MUST support `--auto @file.md` flag to skip interactive questions and extract from a document + +**Produces:** +| Artifact | Description | +|----------|-------------| +| `PROJECT.md` | Project vision, constraints, technical decisions, evolution rules | +| `REQUIREMENTS.md` | Scoped requirements with unique IDs (REQ-XX) | +| `ROADMAP.md` | Phase breakdown with status tracking and requirement mapping | +| `STATE.md` | Initial project state with position, decisions, metrics | +| `config.json` | Workflow configuration | +| `research/SUMMARY.md` | Synthesized domain research | +| `research/STACK.md` | Technology stack investigation | +| `research/FEATURES.md` | Feature implementation patterns | +| `research/ARCHITECTURE.md` | Architecture patterns and trade-offs | +| `research/PITFALLS.md` | Common failure modes and mitigations | + +**Process:** +1. **Questions** — Adaptive questioning guided by the "dream extraction" philosophy (not requirements gathering) +2. **Research** — 4 parallel researcher agents investigate stack, features, architecture, and pitfalls +3. **Synthesis** — Research synthesizer combines findings into SUMMARY.md +4. **Requirements** — Extracted from user responses + research, categorized by scope +5. **Roadmap** — Phase breakdown mapped to requirements, with granularity setting controlling phase count + +**Functional Requirements:** +- Questions adapt based on detected project type (web app, CLI, mobile, API, etc.) +- Research agents have web search capability for current ecosystem information +- Granularity setting controls phase count: `coarse` (3-5), `standard` (5-8), `fine` (8-12) +- `--auto` mode extracts all information from the provided document without interactive questioning +- Existing codebase context (from `/gsd-map-codebase`) is loaded if present + +--- + +### 2. Phase Discussion + +**Command:** `/gsd-discuss-phase [N] [--auto] [--batch]` + +**Purpose:** Capture user's implementation preferences and decisions before research and planning begin. Eliminates the gray areas that cause AI to guess. + +**Requirements:** +- REQ-DISC-01: System MUST analyze the phase scope and identify decision areas (gray areas) +- REQ-DISC-02: System MUST categorize gray areas by type (visual, API, content, organization, etc.) +- REQ-DISC-03: System MUST ask only questions not already answered in prior CONTEXT.md files +- REQ-DISC-04: System MUST persist decisions in `{phase}-CONTEXT.md` with canonical references +- REQ-DISC-05: System MUST support `--auto` flag to auto-select recommended defaults +- REQ-DISC-06: System MUST support `--batch` flag for grouped question intake +- REQ-DISC-07: System MUST scout relevant source files before identifying gray areas (code-aware discussion) + +**Produces:** `{padded_phase}-CONTEXT.md` — User preferences that feed into research and planning + +**Gray Area Categories:** +| Category | Example Decisions | +|----------|-------------------| +| Visual features | Layout, density, interactions, empty states | +| APIs/CLIs | Response format, flags, error handling, verbosity | +| Content systems | Structure, tone, depth, flow | +| Organization | Grouping criteria, naming, duplicates, exceptions | + +--- + +### 3. UI Design Contract + +**Command:** `/gsd-ui-phase [N]` + +**Purpose:** Lock design decisions before planning so that all components in a phase share consistent visual standards. + +**Requirements:** +- REQ-UI-01: System MUST detect existing design system state (shadcn components.json, Tailwind config, tokens) +- REQ-UI-02: System MUST ask only unanswered design contract questions +- REQ-UI-03: System MUST validate against 6 dimensions (Copywriting, Visuals, Color, Typography, Spacing, Registry Safety) +- REQ-UI-04: System MUST enter revision loop if validation returns BLOCKED (max 2 iterations) +- REQ-UI-05: System MUST offer shadcn initialization for React/Next.js/Vite projects without `components.json` +- REQ-UI-06: System MUST enforce registry safety gate for third-party shadcn registries + +**Produces:** `{padded_phase}-UI-SPEC.md` — Design contract consumed by executors + +**6 Validation Dimensions:** +1. **Copywriting** — CTA labels, empty states, error messages +2. **Visuals** — Focal points, visual hierarchy, icon accessibility +3. **Color** — Accent usage discipline, 60/30/10 compliance +4. **Typography** — Font size/weight constraint adherence +5. **Spacing** — Grid alignment, token consistency +6. **Registry Safety** — Third-party component inspection requirements + +**shadcn Integration:** +- Detects missing `components.json` in React/Next.js/Vite projects +- Guides user through `ui.shadcn.com/create` preset configuration +- Preset string becomes a planning artifact reproducible across phases +- Safety gate requires `npx shadcn view` and `npx shadcn diff` before third-party components + +--- + +### 4. Phase Planning + +**Command:** `/gsd-plan-phase [N] [--auto] [--skip-research] [--skip-verify]` + +**Purpose:** Research the implementation domain and produce verified, atomic execution plans. + +**Requirements:** +- REQ-PLAN-01: System MUST spawn a phase researcher to investigate implementation approaches +- REQ-PLAN-02: System MUST produce plans with 2-3 tasks each, sized for a single context window +- REQ-PLAN-03: System MUST structure plans as XML with `` elements containing `name`, `files`, `action`, `verify`, and `done` fields +- REQ-PLAN-04: System MUST include `read_first` and `acceptance_criteria` sections in every plan +- REQ-PLAN-05: System MUST run plan checker verification loop (up to 3 iterations) unless `--skip-verify` is set +- REQ-PLAN-06: System MUST support `--skip-research` flag to bypass research phase +- REQ-PLAN-07: System MUST prompt user to run `/gsd-ui-phase` if frontend phase detected and no UI-SPEC.md exists (UI safety gate) +- REQ-PLAN-08: System MUST include Nyquist validation mapping when `workflow.nyquist_validation` is enabled +- REQ-PLAN-09: System MUST verify all phase requirements are covered by at least one plan before planning completes (requirements coverage gate) + +**Produces:** +| Artifact | Description | +|----------|-------------| +| `{phase}-RESEARCH.md` | Ecosystem research findings | +| `{phase}-{N}-PLAN.md` | Atomic execution plans (2-3 tasks each) | +| `{phase}-VALIDATION.md` | Test coverage mapping (Nyquist layer) | + +**Plan Structure (XML):** +```xml + + Create login endpoint + src/app/api/auth/login/route.ts + + Use jose for JWT. Validate credentials against users table. + Return httpOnly cookie on success. + + curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie + Valid credentials return cookie, invalid return 401 + +``` + +**Plan Checker Verification (8 Dimensions):** +1. Requirement coverage — Plans address all phase requirements +2. task atomicity — Each task is independently committable +3. Dependency ordering — Tasks sequence correctly +4. File scope — No excessive file overlap between plans +5. Verification commands — Each task has testable done criteria +6. Context fit — Tasks fit within a single context window +7. Gap detection — No missing implementation steps +8. Nyquist compliance — Tasks have automated verify commands (when enabled) + +--- + +### 5. Phase Execution + +**Command:** `/gsd-execute-phase ` + +**Purpose:** Execute all plans in a phase using wave-based parallelization with fresh context windows per executor. + +**Requirements:** +- REQ-EXEC-01: System MUST analyze plan dependencies and group into execution waves +- REQ-EXEC-02: System MUST spawn independent plans in parallel within each wave +- REQ-EXEC-03: System MUST give each executor a fresh context window (200K tokens) +- REQ-EXEC-04: System MUST produce atomic git commits per task +- REQ-EXEC-05: System MUST produce a SUMMARY.md for each completed plan +- REQ-EXEC-06: System MUST run post-execution verifier to check phase goals were met +- REQ-EXEC-07: System MUST support git branching strategies (`none`, `phase`, `milestone`) +- REQ-EXEC-08: System MUST invoke node repair operator on task verification failure (when enabled) +- REQ-EXEC-09: System MUST run prior phases' test suites before verification to catch cross-phase regressions + +**Produces:** +| Artifact | Description | +|----------|-------------| +| `{phase}-{N}-SUMMARY.md` | Execution outcomes per plan | +| `{phase}-VERIFICATION.md` | Post-execution verification report | +| Git commits | Atomic commits per task | + +**Wave Execution:** +- Plans with no dependencies → Wave 1 (parallel) +- Plans depending on Wave 1 → Wave 2 (parallel, waits for Wave 1) +- Continues until all plans complete +- File conflicts force sequential execution within same wave + +**Executor Capabilities:** +- Reads PLAN.md with full task instructions +- Has access to PROJECT.md, STATE.md, CONTEXT.md, RESEARCH.md +- Commits each task atomically with structured commit messages +- Uses `--no-verify` on commits during parallel execution to avoid build lock contention +- Handles checkpoint types: `auto`, `checkpoint:human-verify`, `checkpoint:decision`, `checkpoint:human-action` +- Reports deviations from plan in SUMMARY.md + +**Parallel Safety:** +- **Pre-commit hooks**: Skipped by parallel agents (`--no-verify`), run once by orchestrator after each wave +- **STATE.md locking**: File-level lockfile prevents concurrent write corruption across agents + +--- + +### 6. Work Verification + +**Command:** `/gsd-verify-work [N]` + +**Purpose:** User acceptance testing — walk the user through testing each deliverable and auto-diagnose failures. + +**Requirements:** +- REQ-VERIFY-01: System MUST extract testable deliverables from the phase +- REQ-VERIFY-02: System MUST present deliverables one at a time for user confirmation +- REQ-VERIFY-03: System MUST spawn debug agents to diagnose failures automatically +- REQ-VERIFY-04: System MUST create fix plans for identified issues +- REQ-VERIFY-05: System MUST inject cold-start smoke test for phases modifying server/database/seed/startup files +- REQ-VERIFY-06: System MUST produce UAT.md with pass/fail results + +**Produces:** `{phase}-UAT.md` — User acceptance test results, plus fix plans if issues found + +--- + +### 6.5. Ship + +**Command:** `/gsd-ship [N] [--draft]` + +**Purpose:** Bridge local completion → merged PR. After verification passes, push branch, create PR with auto-generated body from planning artifacts, optionally trigger review, and track in STATE.md. + +**Requirements:** +- REQ-SHIP-01: System MUST verify phase has passed verification before shipping +- REQ-SHIP-02: System MUST push branch and create PR via `gh` CLI +- REQ-SHIP-03: System MUST auto-generate PR body from SUMMARY.md, VERIFICATION.md, and REQUIREMENTS.md +- REQ-SHIP-04: System MUST update STATE.md with shipping status and PR number +- REQ-SHIP-05: System MUST support `--draft` flag for draft PRs + +**Prerequisites:** Phase verified, `gh` CLI installed and authenticated, work on feature branch + +**Produces:** GitHub PR with rich body, STATE.md updated + +--- + +### 7. UI Review + +**Command:** `/gsd-ui-review [N]` + +**Purpose:** Retroactive 6-pillar visual audit of implemented frontend code. Works standalone on any project. + +**Requirements:** +- REQ-UIREVIEW-01: System MUST score each of the 6 pillars on a 1-4 scale +- REQ-UIREVIEW-02: System MUST capture screenshots via Playwright CLI to `.planning/ui-reviews/` +- REQ-UIREVIEW-03: System MUST create `.gitignore` for screenshot directory +- REQ-UIREVIEW-04: System MUST identify top 3 priority fixes +- REQ-UIREVIEW-05: System MUST work standalone (without UI-SPEC.md) using abstract quality standards + +**6 Audit Pillars (scored 1-4):** +1. **Copywriting** — CTA labels, empty states, error states +2. **Visuals** — Focal points, visual hierarchy, icon accessibility +3. **Color** — Accent usage discipline, 60/30/10 compliance +4. **Typography** — Font size/weight constraint adherence +5. **Spacing** — Grid alignment, token consistency +6. **Experience Design** — Loading/error/empty state coverage + +**Produces:** `{padded_phase}-UI-REVIEW.md` — Scores and prioritized fixes + +--- + +### 8. Milestone Management + +**Commands:** `/gsd-audit-milestone`, `/gsd-complete-milestone`, `/gsd-new-milestone [name]` + +**Purpose:** Verify milestone completion, archive, tag release, and start the next development cycle. + +**Requirements:** +- REQ-MILE-01: Audit MUST verify all milestone requirements are met +- REQ-MILE-02: Audit MUST detect stubs, placeholder implementations, and untested code +- REQ-MILE-03: Audit MUST check Nyquist validation compliance across phases +- REQ-MILE-04: Complete MUST archive milestone data to MILESTONES.md +- REQ-MILE-05: Complete MUST offer git tag creation for the release +- REQ-MILE-06: Complete MUST offer squash merge or merge with history for branching strategies +- REQ-MILE-07: Complete MUST clean up UI review screenshots +- REQ-MILE-08: New milestone MUST follow same flow as new-project (questions → research → requirements → roadmap) +- REQ-MILE-09: New milestone MUST NOT reset existing workflow configuration + +**Gap Closure:** `/gsd-plan-milestone-gaps` creates phases to close gaps identified by audit. + +--- + +## Planning Features + +### 9. Phase Management + +**Commands:** `/gsd-add-phase`, `/gsd-insert-phase [N]`, `/gsd-remove-phase [N]` + +**Purpose:** Dynamic roadmap modification during development. + +**Requirements:** +- REQ-PHASE-01: Add MUST append a new phase to the end of the current roadmap +- REQ-PHASE-02: Insert MUST use decimal numbering (e.g., 3.1) between existing phases +- REQ-PHASE-03: Remove MUST renumber all subsequent phases +- REQ-PHASE-04: Remove MUST prevent removing phases that have been executed +- REQ-PHASE-05: All operations MUST update ROADMAP.md and create/remove phase directories + +--- + +### 10. Quick Mode + +**Command:** `/gsd-quick [--full] [--discuss] [--research]` + +**Purpose:** Ad-hoc task execution with GSD guarantees but a faster path. + +**Requirements:** +- REQ-QUICK-01: System MUST accept freeform task description +- REQ-QUICK-02: System MUST use same planner + executor agents as full workflow +- REQ-QUICK-03: System MUST skip research, plan checker, and verifier by default +- REQ-QUICK-04: `--full` flag MUST enable plan checking (max 2 iterations) and post-execution verification +- REQ-QUICK-05: `--discuss` flag MUST run lightweight pre-planning discussion +- REQ-QUICK-06: `--research` flag MUST spawn focused research agent before planning +- REQ-QUICK-07: Flags MUST be composable (`--discuss --research --full`) +- REQ-QUICK-08: System MUST track quick tasks in `.planning/quick/YYMMDD-xxx-slug/` +- REQ-QUICK-09: System MUST produce atomic commits for quick task execution + +--- + +### 11. Autonomous Mode + +**Command:** `/gsd-autonomous [--from N]` + +**Purpose:** Run all remaining phases autonomously — discuss → plan → execute per phase. + +**Requirements:** +- REQ-AUTO-01: System MUST iterate through all incomplete phases in roadmap order +- REQ-AUTO-02: System MUST run discuss → plan → execute for each phase +- REQ-AUTO-03: System MUST pause for explicit user decisions (gray area acceptance, blockers, validation) +- REQ-AUTO-04: System MUST re-read ROADMAP.md after each phase to catch dynamically inserted phases +- REQ-AUTO-05: `--from N` flag MUST start from a specific phase number + +--- + +### 12. Freeform Routing + +**Command:** `/gsd-do` + +**Purpose:** Analyze freeform text and route to the appropriate GSD command. + +**Requirements:** +- REQ-DO-01: System MUST parse user intent from natural language input +- REQ-DO-02: System MUST map intent to the best matching GSD command +- REQ-DO-03: System MUST confirm the routing with the user before executing +- REQ-DO-04: System MUST handle project-exists vs no-project contexts differently + +--- + +### 13. Note Capture + +**Command:** `/gsd-note` + +**Purpose:** Zero-friction idea capture without interrupting workflow. Append timestamped notes, list all notes, or promote notes to structured todos. + +**Requirements:** +- REQ-NOTE-01: System MUST save timestamped note files with a single write call +- REQ-NOTE-02: System MUST support `list` subcommand to show all notes from project and global scopes +- REQ-NOTE-03: System MUST support `promote N` subcommand to convert a note into a structured todo +- REQ-NOTE-04: System MUST support `--global` flag for global scope operations +- REQ-NOTE-05: System MUST NOT use task, question, or bash — runs inline only + +--- + +### 14. Auto-Advance (Next) + +**Command:** `/gsd-next` + +**Purpose:** Automatically detect current project state and advance to the next logical workflow step, eliminating the need to remember which phase/step you're on. + +**Requirements:** +- REQ-NEXT-01: System MUST read STATE.md, ROADMAP.md, and phase directories to determine current position +- REQ-NEXT-02: System MUST detect whether discuss, plan, execute, or verify is needed +- REQ-NEXT-03: System MUST invoke the correct command automatically +- REQ-NEXT-04: System MUST suggest `/gsd-new-project` if no project exists +- REQ-NEXT-05: System MUST suggest `/gsd-complete-milestone` when all phases are complete + +**State Detection Logic:** +| State | Action | +|-------|--------| +| No `.planning/` directory | Suggest `/gsd-new-project` | +| Phase has no CONTEXT.md | Run `/gsd-discuss-phase` | +| Phase has no PLAN.md files | Run `/gsd-plan-phase` | +| Phase has plans but no SUMMARY.md | Run `/gsd-execute-phase` | +| Phase executed but no VERIFICATION.md | Run `/gsd-verify-work` | +| All phases complete | Suggest `/gsd-complete-milestone` | + +--- + +## Quality Assurance Features + +### 15. Nyquist Validation + +**Purpose:** Map automated test coverage to phase requirements before any code is written. Named after the Nyquist sampling theorem — ensures a feedback signal exists for every requirement. + +**Requirements:** +- REQ-NYQ-01: System MUST detect existing test infrastructure during plan-phase research +- REQ-NYQ-02: System MUST map each requirement to a specific test command +- REQ-NYQ-03: System MUST identify Wave 0 tasks (test scaffolding needed before implementation) +- REQ-NYQ-04: Plan checker MUST enforce Nyquist compliance as 8th verification dimension +- REQ-NYQ-05: System MUST support retroactive validation via `/gsd-validate-phase` +- REQ-NYQ-06: System MUST be disableable via `workflow.nyquist_validation: false` + +**Produces:** `{phase}-VALIDATION.md` — Test coverage contract + +**Retroactive Validation (`/gsd-validate-phase [N]`):** +- Scans implementation and maps requirements to tests +- Identifies gaps where requirements lack automated verification +- Spawns auditor to generate tests (max 3 attempts) +- Never modifies implementation code — only test files and VALIDATION.md +- Flags implementation bugs as escalations for user to address + +--- + +### 16. Plan Checking + +**Purpose:** Goal-backward verification that plans will achieve phase objectives before execution. + +**Requirements:** +- REQ-PLANCK-01: System MUST verify plans against 8 quality dimensions +- REQ-PLANCK-02: System MUST loop up to 3 iterations until plans pass +- REQ-PLANCK-03: System MUST produce specific, actionable feedback on failures +- REQ-PLANCK-04: System MUST be disableable via `workflow.plan_check: false` + +--- + +### 17. Post-Execution Verification + +**Purpose:** Automated check that the codebase delivers what the phase promised. + +**Requirements:** +- REQ-POSTVER-01: System MUST check against phase goals, not just task completion +- REQ-POSTVER-02: System MUST produce VERIFICATION.md with pass/fail analysis +- REQ-POSTVER-03: System MUST log issues for `/gsd-verify-work` to address +- REQ-POSTVER-04: System MUST be disableable via `workflow.verifier: false` + +--- + +### 18. Node Repair + +**Purpose:** Autonomous recovery when task verification fails during execution. + +**Requirements:** +- REQ-REPAIR-01: System MUST analyze failure and choose one strategy: RETRY, DECOMPOSE, or PRUNE +- REQ-REPAIR-02: RETRY MUST attempt with a concrete adjustment +- REQ-REPAIR-03: DECOMPOSE MUST break task into smaller verifiable sub-steps +- REQ-REPAIR-04: PRUNE MUST remove unachievable tasks and escalate to user +- REQ-REPAIR-05: System MUST respect repair budget (default: 2 attempts per task) +- REQ-REPAIR-06: System MUST be configurable via `workflow.node_repair_budget` and `workflow.node_repair` + +--- + +### 19. Health Validation + +**Command:** `/gsd-health [--repair]` + +**Purpose:** Validate `.planning/` directory integrity and auto-repair issues. + +**Requirements:** +- REQ-HEALTH-01: System MUST check for missing required files +- REQ-HEALTH-02: System MUST validate configuration consistency +- REQ-HEALTH-03: System MUST detect orphaned plans without summaries +- REQ-HEALTH-04: System MUST check phase numbering and roadmap sync +- REQ-HEALTH-05: `--repair` flag MUST auto-fix recoverable issues + +--- + +### 20. Cross-Phase Regression Gate + +**Purpose:** Prevent regressions from compounding across phases by running prior phases' test suites after execution. + +**Requirements:** +- REQ-REGR-01: System MUST run test suites from all completed prior phases after phase execution +- REQ-REGR-02: System MUST report any test failures as cross-phase regressions +- REQ-REGR-03: Regressions MUST be surfaced before post-execution verification +- REQ-REGR-04: System MUST identify which prior phase's tests were broken + +**When:** Runs automatically during `/gsd-execute-phase` before the verifier step. + +--- + +### 21. Requirements Coverage Gate + +**Purpose:** Ensure all phase requirements are covered by at least one plan before planning completes. + +**Requirements:** +- REQ-COVGATE-01: System MUST extract all requirement IDs assigned to the phase from ROADMAP.md +- REQ-COVGATE-02: System MUST verify each requirement appears in at least one PLAN.md +- REQ-COVGATE-03: Uncovered requirements MUST block planning completion +- REQ-COVGATE-04: System MUST report which specific requirements lack plan coverage + +**When:** Runs automatically at the end of `/gsd-plan-phase` after the plan checker loop. + +--- + +## Context Engineering Features + +### 22. Context Window Monitoring + +**Purpose:** Prevent context rot by alerting both user and agent when context is running low. + +**Requirements:** +- REQ-CTX-01: Statusline MUST display context usage percentage to user +- REQ-CTX-02: Context monitor MUST inject agent-facing warnings at ≤35% remaining (WARNING) +- REQ-CTX-03: Context monitor MUST inject agent-facing warnings at ≤25% remaining (CRITICAL) +- REQ-CTX-04: Warnings MUST debounce (5 tool uses between repeated warnings) +- REQ-CTX-05: Severity escalation (WARNING→CRITICAL) MUST bypass debounce +- REQ-CTX-06: Context monitor MUST differentiate GSD-active vs non-GSD-active projects +- REQ-CTX-07: Warnings MUST be advisory, never imperative commands that override user preferences +- REQ-CTX-08: All hooks MUST fail silently and never block tool execution + +**Architecture:** Two-part bridge system: +1. Statusline writes metrics to `/tmp/OpenCode-ctx-{session}.json` +2. Context monitor reads metrics and injects `additionalContext` warnings + +--- + +### 23. Session Management + +**Commands:** `/gsd-pause-work`, `/gsd-resume-work`, `/gsd-progress` + +**Purpose:** Maintain project continuity across context resets and sessions. + +**Requirements:** +- REQ-SESSION-01: Pause MUST save current position and next steps to `continue-here.md` and structured `HANDOFF.json` +- REQ-SESSION-02: Resume MUST restore full project context from HANDOFF.json (preferred) or state files (fallback) +- REQ-SESSION-03: Progress MUST show current position, next action, and overall completion +- REQ-SESSION-04: Progress MUST read all state files (STATE.md, ROADMAP.md, phase directories) +- REQ-SESSION-05: All session operations MUST work after `/new` (context reset) +- REQ-SESSION-06: HANDOFF.json MUST include blockers, human actions pending, and in-progress task state +- REQ-SESSION-07: Resume MUST surface human actions and blockers immediately on session start + +--- + +### 24. Session Reporting + +**Command:** `/gsd-session-report` + +**Purpose:** Generate a structured post-session summary document capturing work performed, outcomes achieved, and estimated resource usage. + +**Requirements:** +- REQ-REPORT-01: System MUST gather data from STATE.md, git log, and plan/summary files +- REQ-REPORT-02: System MUST include commits made, plans executed, and phases progressed +- REQ-REPORT-03: System MUST estimate token usage and cost based on session activity +- REQ-REPORT-04: System MUST include active blockers and decisions made +- REQ-REPORT-05: System MUST recommend next steps + +**Produces:** `.planning/reports/SESSION_REPORT.md` + +**Report Sections:** +- Session overview (duration, milestone, phase) +- Work performed (commits, plans, phases) +- Outcomes and deliverables +- Blockers and decisions +- Resource estimates (tokens, cost) +- Next steps recommendation + +--- + +### 25. Multi-Agent Orchestration + +**Purpose:** Coordinate specialized agents with fresh context windows for each task. + +**Requirements:** +- REQ-ORCH-01: Each agent MUST receive a fresh context window +- REQ-ORCH-02: Orchestrators MUST be thin — spawn agents, collect results, route next +- REQ-ORCH-03: Context payload MUST include all relevant project artifacts +- REQ-ORCH-04: Parallel agents MUST be truly independent (no shared mutable state) +- REQ-ORCH-05: Agent results MUST be written to disk before orchestrator processes them +- REQ-ORCH-06: Failed agents MUST be detected (spot-check actual output vs reported failure) + +--- + +### 26. Model Profiles + +**Command:** `/gsd-set-profile ` + +**Purpose:** Control which AI model each agent uses, balancing quality vs cost. + +**Requirements:** +- REQ-MODEL-01: System MUST support 4 profiles: `quality`, `balanced`, `budget`, `inherit` +- REQ-MODEL-02: Each profile MUST define model tier per agent (see profile table) +- REQ-MODEL-03: Per-agent overrides MUST take precedence over profile +- REQ-MODEL-04: `inherit` profile MUST defer to runtime's current model selection +- REQ-MODEL-04a: `inherit` profile MUST be used when running non-Anthropic providers (OpenRouter, local models) to avoid unexpected API costs +- REQ-MODEL-05: Profile switch MUST be programmatic (script, not LLM-driven) +- REQ-MODEL-06: Model resolution MUST happen once per orchestration, not per spawn + +**Profile Assignments:** + +| Agent | `quality` | `balanced` | `budget` | `inherit` | +|-------|-----------|------------|----------|-----------| +| gsd-planner | Opus | Opus | Sonnet | Inherit | +| gsd-roadmapper | Opus | Sonnet | Sonnet | Inherit | +| gsd-executor | Opus | Sonnet | Sonnet | Inherit | +| gsd-phase-researcher | Opus | Sonnet | Haiku | Inherit | +| gsd-project-researcher | Opus | Sonnet | Haiku | Inherit | +| gsd-research-synthesizer | Sonnet | Sonnet | Haiku | Inherit | +| gsd-debugger | Opus | Sonnet | Sonnet | Inherit | +| gsd-codebase-mapper | Sonnet | Haiku | Haiku | Inherit | +| gsd-verifier | Sonnet | Sonnet | Haiku | Inherit | +| gsd-plan-checker | Sonnet | Sonnet | Haiku | Inherit | +| gsd-integration-checker | Sonnet | Sonnet | Haiku | Inherit | +| gsd-nyquist-auditor | Sonnet | Sonnet | Haiku | Inherit | + +--- + +## Brownfield Features + +### 27. Codebase Mapping + +**Command:** `/gsd-map-codebase [area]` + +**Purpose:** Analyze an existing codebase before starting a new project, so GSD understands what exists. + +**Requirements:** +- REQ-MAP-01: System MUST spawn parallel mapper agents for each analysis area +- REQ-MAP-02: System MUST produce structured documents in `.planning/codebase/` +- REQ-MAP-03: System MUST detect: tech stack, architecture patterns, coding conventions, concerns +- REQ-MAP-04: Subsequent `/gsd-new-project` MUST load codebase mapping and focus questions on what's being added +- REQ-MAP-05: Optional `[area]` argument MUST scope mapping to a specific area + +**Produces:** +| Document | Content | +|----------|---------| +| `STACK.md` | Languages, frameworks, databases, infrastructure | +| `ARCHITECTURE.md` | Patterns, layers, data flow, boundaries | +| `CONVENTIONS.md` | Naming, file organization, code style, testing patterns | +| `CONCERNS.md` | Technical debt, security issues, performance bottlenecks | +| `STRUCTURE.md` | Directory layout and file organization | +| `TESTING.md` | Test infrastructure, coverage, patterns | +| `INTEGRATIONS.md` | External services, APIs, third-party dependencies | + +--- + +## Utility Features + +### 28. Debug System + +**Command:** `/gsd-debug [description]` + +**Purpose:** Systematic debugging with persistent state across context resets. + +**Requirements:** +- REQ-DEBUG-01: System MUST create debug session file in `.planning/debug/` +- REQ-DEBUG-02: System MUST track hypotheses, evidence, and eliminated theories +- REQ-DEBUG-03: System MUST persist state so debugging survives context resets +- REQ-DEBUG-04: System MUST require human verification before marking resolved +- REQ-DEBUG-05: Resolved sessions MUST append to `.planning/debug/knowledge-base.md` +- REQ-DEBUG-06: Knowledge base MUST be consulted on new debug sessions to prevent re-investigation + +**Debug Session States:** `gathering` → `investigating` → `fixing` → `verifying` → `awaiting_human_verify` → `resolved` + +--- + +### 29. Todo Management + +**Commands:** `/gsd-add-todo [desc]`, `/gsd-check-todos` + +**Purpose:** Capture ideas and tasks during sessions for later work. + +**Requirements:** +- REQ-TODO-01: System MUST capture todo from current conversation context +- REQ-TODO-02: Todos MUST be stored in `.planning/todos/pending/` +- REQ-TODO-03: Completed todos MUST move to `.planning/todos/done/` +- REQ-TODO-04: Check-todos MUST list all pending items with selection to work on one + +--- + +### 30. Statistics Dashboard + +**Command:** `/gsd-stats` + +**Purpose:** Display project metrics — phases, plans, requirements, git history, and timeline. + +**Requirements:** +- REQ-STATS-01: System MUST show phase/plan completion counts +- REQ-STATS-02: System MUST show requirement coverage +- REQ-STATS-03: System MUST show git commit metrics +- REQ-STATS-04: System MUST support multiple output formats (json, table, bar) + +--- + +### 31. Update System + +**Command:** `/gsd-update` + +**Purpose:** Update GSD to the latest version with changelog preview. + +**Requirements:** +- REQ-UPDATE-01: System MUST check for new versions via npm +- REQ-UPDATE-02: System MUST display changelog for new version before updating +- REQ-UPDATE-03: System MUST be runtime-aware and target the correct directory +- REQ-UPDATE-04: System MUST back up locally modified files to `gsd-local-patches/` +- REQ-UPDATE-05: `/gsd-reapply-patches` MUST restore local modifications after update + +--- + +### 32. Settings Management + +**Command:** `/gsd-settings` + +**Purpose:** Interactive configuration of workflow toggles and model profile. + +**Requirements:** +- REQ-SETTINGS-01: System MUST present current settings with toggle options +- REQ-SETTINGS-02: System MUST update `.planning/config.json` +- REQ-SETTINGS-03: System MUST support saving as global defaults (`~/.gsd/defaults.json`) + +**Configurable Settings:** +| Setting | Type | Default | Description | +|---------|------|---------|-------------| +| `mode` | enum | `interactive` | `interactive` or `yolo` (auto-approve) | +| `granularity` | enum | `standard` | `coarse`, `standard`, or `fine` | +| `model_profile` | enum | `balanced` | `quality`, `balanced`, `budget`, or `inherit` | +| `workflow.research` | boolean | `true` | Domain research before planning | +| `workflow.plan_check` | boolean | `true` | Plan verification loop | +| `workflow.verifier` | boolean | `true` | Post-execution verification | +| `workflow.auto_advance` | boolean | `false` | Auto-chain discuss→plan→execute | +| `workflow.nyquist_validation` | boolean | `true` | Nyquist test coverage mapping | +| `workflow.ui_phase` | boolean | `true` | UI design contract generation | +| `workflow.ui_safety_gate` | boolean | `true` | Prompt for ui-phase on frontend phases | +| `workflow.node_repair` | boolean | `true` | Autonomous task repair | +| `workflow.node_repair_budget` | number | `2` | Max repair attempts per task | +| `planning.commit_docs` | boolean | `true` | Commit `.planning/` files to git | +| `planning.search_gitignored` | boolean | `false` | Include gitignored files in searches | +| `parallelization.enabled` | boolean | `true` | Run independent plans simultaneously | +| `git.branching_strategy` | enum | `none` | `none`, `phase`, or `milestone` | + +--- + +### 33. Test Generation + +**Command:** `/gsd-add-tests [N]` + +**Purpose:** Generate tests for a completed phase based on UAT criteria and implementation. + +**Requirements:** +- REQ-TEST-01: System MUST analyze completed phase implementation +- REQ-TEST-02: System MUST generate tests based on UAT criteria and acceptance criteria +- REQ-TEST-03: System MUST use existing test infrastructure patterns + +--- + +## Infrastructure Features + +### 34. Git Integration + +**Purpose:** Atomic commits, branching strategies, and clean history management. + +**Requirements:** +- REQ-GIT-01: Each task MUST get its own atomic commit +- REQ-GIT-02: Commit messages MUST follow structured format: `type(scope): description` +- REQ-GIT-03: System MUST support 3 branching strategies: `none`, `phase`, `milestone` +- REQ-GIT-04: Phase strategy MUST create one branch per phase +- REQ-GIT-05: Milestone strategy MUST create one branch per milestone +- REQ-GIT-06: Complete-milestone MUST offer squash merge (recommended) or merge with history +- REQ-GIT-07: System MUST respect `commit_docs` setting for `.planning/` files +- REQ-GIT-08: System MUST auto-detect `.planning/` in `.gitignore` and skip commits + +**Commit Format:** +``` +type(phase-plan): description + +# Examples: +docs(08-02): complete user registration plan +feat(08-02): add email confirmation flow +fix(03-01): correct auth token expiry +``` + +--- + +### 35. CLI Tools + +**Purpose:** Programmatic utilities for workflows and agents, replacing repetitive inline bash patterns. + +**Requirements:** +- REQ-CLI-01: System MUST provide atomic commands for state, config, phase, roadmap operations +- REQ-CLI-02: System MUST provide compound `init` commands that load all context for each workflow +- REQ-CLI-03: System MUST support `--raw` flag for machine-readable output +- REQ-CLI-04: System MUST support `--cwd` flag for sandboxed subagent operation +- REQ-CLI-05: All operations MUST use forward-slash paths on Windows + +**Command Categories:** State (11 subcommands), Phase (5), Roadmap (3), Verify (8), Template (2), Frontmatter (4), Scaffold (4), Init (12), Validate (2), Progress, Stats, Todo + +--- + +### 36. Multi-Runtime Support + +**Purpose:** Run GSD across 6 different AI coding agent runtimes. + +**Requirements:** +- REQ-RUNTIME-01: System MUST support OpenCode, OpenCode, Gemini CLI, Codex, Copilot, Antigravity +- REQ-RUNTIME-02: Installer MUST transform content per runtime (tool names, paths, frontmatter) +- REQ-RUNTIME-03: Installer MUST support interactive and non-interactive (`--OpenCode --global`) modes +- REQ-RUNTIME-04: Installer MUST support both global and local installation +- REQ-RUNTIME-05: Uninstall MUST cleanly remove all GSD files without affecting other configurations +- REQ-RUNTIME-06: Installer MUST handle platform differences (Windows, macOS, Linux, WSL, Docker) + +**Runtime Transformations:** + +| Aspect | OpenCode | OpenCode | Gemini | Codex | Copilot | Antigravity | +|--------|------------|----------|--------|-------|---------|-------------| +| Commands | Slash commands | Slash commands | Slash commands | Skills (TOML) | Slash commands | Skills | +| Agent format | OpenCode native | `mode: subagent` | OpenCode native | Skills | Tool mapping | Skills | +| Hook events | `PostToolUse` | N/A | `AfterTool` | N/A | N/A | N/A | +| Config | `settings.json` | `opencode.json(c)` | `settings.json` | TOML | Instructions | Config | + +--- + +### 37. Hook System + +**Purpose:** Runtime event hooks for context monitoring, status display, and update checking. + +**Requirements:** +- REQ-HOOK-01: Statusline MUST display model, current task, directory, and context usage +- REQ-HOOK-02: Context monitor MUST inject agent-facing warnings at threshold levels +- REQ-HOOK-03: Update checker MUST run in background on session start +- REQ-HOOK-04: All hooks MUST respect `CLAUDE_CONFIG_DIR` env var +- REQ-HOOK-05: All hooks MUST include 3-second stdin timeout guard +- REQ-HOOK-06: All hooks MUST fail silently on any error +- REQ-HOOK-07: Context usage MUST normalize for autocompact buffer (16.5% reserved) + +**Statusline Display:** +``` +[⬆ /gsd-update │] model │ [current task │] directory [█████░░░░░ 50%] +``` + +Color coding: <50% green, <65% yellow, <80% orange, ≥80% red with skull emoji + +### 38. Developer Profiling + +**Command:** `/gsd-profile-user [--questionnaire] [--refresh]` + +**Purpose:** Analyze OpenCode session history to build behavioral profiles across 8 dimensions, generating artifacts that personalize OpenCode's responses to the developer's style. + +**Dimensions:** +1. Communication style (terse vs verbose, formal vs casual) +2. Decision patterns (rapid vs deliberate, risk tolerance) +3. Debugging approach (systematic vs intuitive, log preference) +4. UX preferences (design sensibility, accessibility awareness) +5. Vendor/technology choices (framework preferences, ecosystem familiarity) +6. Frustration triggers (what causes friction in workflows) +7. Learning style (documentation vs examples, depth preference) +8. Explanation depth (high-level vs implementation detail) + +**Generated Artifacts:** +- `USER-PROFILE.md` — Full behavioral profile with evidence citations +- `/gsd-dev-preferences` command — Load preferences in any session +- `AGENTS.md` profile section — Auto-discovered by OpenCode + +**Flags:** +- `--questionnaire` — Interactive questionnaire fallback when session history is unavailable +- `--refresh` — Re-analyze sessions and regenerate profile + +**Pipeline Modules:** +- `profile-pipeline.cjs` — Session scanning, message extraction, sampling +- `profile-output.cjs` — Profile rendering, questionnaire, artifact generation +- `gsd-user-profiler` agent — Behavioral analysis from session data + +**Requirements:** +- REQ-PROF-01: Session analysis MUST cover at least 8 behavioral dimensions +- REQ-PROF-02: Profile MUST cite evidence from actual session messages +- REQ-PROF-03: Questionnaire MUST be available as fallback when no session history exists +- REQ-PROF-04: Generated artifacts MUST be discoverable by OpenCode (AGENTS.md integration) + +### 39. Execution Hardening + +**Purpose:** Three additive quality improvements to the execution pipeline that catch cross-plan failures before they cascade. + +**Components:** + +**1. Pre-Wave Dependency Check** (execute-phase) +Before spawning wave N+1, verify key-links from prior wave artifacts exist and are wired correctly. Catches cross-plan dependency gaps before they cascade into downstream failures. + +**2. Cross-Plan Data Contracts — Dimension 9** (plan-checker) +New analysis dimension that checks plans sharing data pipelines have compatible transformations. Flags when one plan strips data that another plan needs in its original form. + +**3. Export-Level Spot Check** (verify-phase) +After Level 3 wiring verification passes, spot-check individual exports for actual usage. Catches dead stores that exist in wired files but are never called. + +**Requirements:** +- REQ-HARD-01: Pre-wave check MUST verify key-links from all prior wave artifacts before spawning next wave +- REQ-HARD-02: Cross-plan contract check MUST detect incompatible data transformations between plans +- REQ-HARD-03: Export spot-check MUST identify dead stores in wired files + +--- + +### 40. Verification Debt Tracking + +**Command:** `/gsd-audit-uat` + +**Purpose:** Prevent silent loss of UAT/verification items when projects advance past phases with outstanding tests. Surfaces verification debt across all prior phases so items are never forgotten. + +**Components:** + +**1. Cross-Phase Health Check** (progress.md Step 1.6) +Every `/gsd-progress` call scans ALL phases in the current milestone for outstanding items (pending, skipped, blocked, human_needed). Displays a non-blocking warning section with actionable links. + +**2. `status: partial`** (verify-work.md, UAT.md) +New UAT status that distinguishes between "session ended" and "all tests resolved". Prevents `status: complete` when tests are still pending, blocked, or skipped without reason. + +**3. `result: blocked` with `blocked_by` tag** (verify-work.md, UAT.md) +New test result type for tests blocked by external dependencies (server, physical device, release build, third-party services). Categorized separately from skipped tests. + +**4. HUMAN-UAT.md Persistence** (execute-phase.md) +When verification returns `human_needed`, items are persisted as a trackable HUMAN-UAT.md file with `status: partial`. Feeds into the cross-phase health check and audit systems. + +**5. Phase Completion Warnings** (phase.cjs, transition.md) +`phase complete` CLI returns verification debt warnings in its JSON output. Transition workflow surfaces outstanding items before confirmation. + +**Requirements:** +- REQ-DEBT-01: System MUST surface outstanding UAT/verification items from ALL prior phases in `/gsd-progress` +- REQ-DEBT-02: System MUST distinguish incomplete testing (partial) from completed testing (complete) +- REQ-DEBT-03: System MUST categorize blocked tests with `blocked_by` tags +- REQ-DEBT-04: System MUST persist human_needed verification items as trackable UAT files +- REQ-DEBT-05: System MUST warn (non-blocking) during phase completion and transition when verification debt exists +- REQ-DEBT-06: `/gsd-audit-uat` MUST scan all phases, categorize items by testability, and produce a human test plan + +--- + +## v1.27 Features + +### 41. Fast Mode + +**Command:** `/gsd-fast [task description]` + +**Purpose:** Execute trivial tasks inline without spawning subagents or generating PLAN.md files. For tasks too small to justify planning overhead: typo fixes, config changes, small refactors, forgotten commits, simple additions. + +**Requirements:** +- REQ-FAST-01: System MUST execute the task directly in the current context without subagents +- REQ-FAST-02: System MUST produce an atomic git commit for the change +- REQ-FAST-03: System MUST track the task in `.planning/quick/` for state consistency +- REQ-FAST-04: System MUST NOT be used for tasks requiring research, multi-step planning, or verification + +**When to use vs `/gsd-quick`:** +- `/gsd-fast` — One-sentence tasks executable in under 2 minutes (typo, config change, small addition) +- `/gsd-quick` — Anything needing research, multi-step planning, or verification + +--- + +### 42. Cross-AI Peer Review + +**Command:** `/gsd-review --phase N [--gemini] [--OpenCode] [--codex] [--all]` + +**Purpose:** Invoke external AI CLIs (Gemini, OpenCode, Codex) to independently review phase plans. Produces structured REVIEWS.md with per-reviewer feedback. + +**Requirements:** +- REQ-REVIEW-01: System MUST detect available AI CLIs on the system +- REQ-REVIEW-02: System MUST build a structured review prompt from phase plans +- REQ-REVIEW-03: System MUST invoke each selected CLI independently +- REQ-REVIEW-04: System MUST collect responses and produce `REVIEWS.md` +- REQ-REVIEW-05: Reviews MUST be consumable by `/gsd-plan-phase --reviews` + +**Produces:** `{phase}-REVIEWS.md` — Per-reviewer structured feedback + +--- + +### 43. Backlog Parking Lot + +**Commands:** `/gsd-add-backlog `, `/gsd-review-backlog`, `/gsd-plant-seed ` + +**Purpose:** Capture ideas that aren't ready for active planning. Backlog items use 999.x numbering to stay outside the active phase sequence. Seeds are forward-looking ideas with trigger conditions that surface automatically at the right milestone. + +**Requirements:** +- REQ-BACKLOG-01: Backlog items MUST use 999.x numbering to stay outside active phase sequence +- REQ-BACKLOG-02: Phase directories MUST be created immediately so `/gsd-discuss-phase` and `/gsd-plan-phase` work on them +- REQ-BACKLOG-03: `/gsd-review-backlog` MUST support promote, keep, and remove actions per item +- REQ-BACKLOG-04: Promoted items MUST be renumbered into the active milestone sequence +- REQ-SEED-01: Seeds MUST capture the full WHY and WHEN to surface conditions +- REQ-SEED-02: `/gsd-new-milestone` MUST scan seeds and present matches + +**Produces:** +| Artifact | Description | +|----------|-------------| +| `.planning/phases/999.x-slug/` | Backlog item directory | +| `.planning/seeds/SEED-NNN-slug.md` | Seed with trigger conditions | + +--- + +### 44. Persistent Context Threads + +**Command:** `/gsd-thread [name | description]` + +**Purpose:** Lightweight cross-session knowledge stores for work that spans multiple sessions but doesn't belong to any specific phase. Lighter weight than `/gsd-pause-work` — no phase state, no plan context. + +**Requirements:** +- REQ-THREAD-01: System MUST support create, list, and resume modes +- REQ-THREAD-02: Threads MUST be stored in `.planning/threads/` as markdown files +- REQ-THREAD-03: Thread files MUST include Goal, Context, References, and Next Steps sections +- REQ-THREAD-04: Resuming a thread MUST load its full context into the current session +- REQ-THREAD-05: Threads MUST be promotable to phases or backlog items + +**Produces:** `.planning/threads/{slug}.md` — Persistent context thread + +--- + +### 45. PR Branch Filtering + +**Command:** `/gsd-pr-branch [target branch]` + +**Purpose:** Create a clean branch suitable for pull requests by filtering out `.planning/` commits. Reviewers see only code changes, not GSD planning artifacts. + +**Requirements:** +- REQ-PRBRANCH-01: System MUST identify commits that only modify `.planning/` files +- REQ-PRBRANCH-02: System MUST create a new branch with planning commits filtered out +- REQ-PRBRANCH-03: Code changes MUST be preserved exactly as committed + +--- + +### 46. Security Hardening + +**Purpose:** Defense-in-depth security for GSD's planning artifacts. Because GSD generates markdown files that become LLM system prompts, user-controlled text flowing into these files is a potential indirect prompt injection vector. + +**Components:** + +**1. Centralized Security Module** (`security.cjs`) +- Path traversal prevention — validates file paths resolve within the project directory +- Prompt injection detection — scans for known injection patterns in user-supplied text +- Safe JSON parsing — catches malformed input before state corruption +- Field name validation — prevents injection through config field names +- Shell argument validation — sanitizes user text before shell interpolation + +**2. Prompt Injection Guard Hook** (`gsd-prompt-guard.js`) +PreToolUse hook that scans write/edit calls targeting `.planning/` for injection patterns. Advisory-only — logs detection for awareness without blocking legitimate operations. + +**3. Workflow Guard Hook** (`gsd-workflow-guard.js`) +PreToolUse hook that detects when OpenCode attempts file edits outside a GSD workflow context. Advises using `/gsd-quick` or `/gsd-fast` instead of direct edits. Configurable via `hooks.workflow_guard` (default: false). + +**4. CI-Ready Injection Scanner** (`prompt-injection-scan.test.cjs`) +Test suite that scans all agent, workflow, and command files for embedded injection vectors. + +**Requirements:** +- REQ-SEC-01: All user-supplied file paths MUST be validated against the project directory +- REQ-SEC-02: Prompt injection patterns MUST be detected before text enters planning artifacts +- REQ-SEC-03: Security hooks MUST be advisory-only (never block legitimate operations) +- REQ-SEC-04: JSON parsing of user input MUST catch malformed data gracefully +- REQ-SEC-05: macOS `/var` → `/private/var` symlink resolution MUST be handled in path validation + +--- + +### 47. Multi-Repo Workspace Support + +**Purpose:** Auto-detection and project root resolution for monorepos and multi-repo setups. Supports workspaces where `.planning/` may need to resolve across repository boundaries. + +**Requirements:** +- REQ-MULTIREPO-01: System MUST auto-detect multi-repo workspace configuration +- REQ-MULTIREPO-02: System MUST resolve project root across repository boundaries +- REQ-MULTIREPO-03: Executor MUST record per-repo commit hashes in multi-repo mode + +--- + +### 48. Discussion Audit Trail + +**Purpose:** Auto-generate `DISCUSSION-LOG.md` during `/gsd-discuss-phase` for full audit trail of decisions made during discussion. + +**Requirements:** +- REQ-DISCLOG-01: System MUST auto-generate DISCUSSION-LOG.md during discuss-phase +- REQ-DISCLOG-02: Log MUST capture questions asked, options presented, and decisions made +- REQ-DISCLOG-03: Decision IDs MUST enable traceability from discuss-phase to plan-phase + +--- + +## v1.28 Features + +### 49. Forensics + +**Command:** `/gsd-forensics [description]` + +**Purpose:** Post-mortem investigation of failed or stuck GSD workflows. + +**Requirements:** +- REQ-FORENSICS-01: System MUST analyze git history for anomalies (stuck loops, long gaps, repeated commits) +- REQ-FORENSICS-02: System MUST check artifact integrity (completed phases have expected files) +- REQ-FORENSICS-03: System MUST generate a markdown report saved to `.planning/forensics/` +- REQ-FORENSICS-04: System MUST offer to create a GitHub issue with findings +- REQ-FORENSICS-05: System MUST NOT modify project files (read-only investigation) + +**Produces:** +| Artifact | Description | +|----------|-------------| +| `.planning/forensics/report-{timestamp}.md` | Post-mortem investigation report | + +**Process:** +1. **Scan** — Analyze git history for anomalies: stuck loops, long gaps between commits, repeated identical commits +2. **Integrity Check** — Verify completed phases have expected artifact files +3. **Report** — Generate markdown report with findings, saved to `.planning/forensics/` +4. **Issue** — Offer to create a GitHub issue with findings for team visibility + +--- + +### 50. Milestone Summary + +**Command:** `/gsd-milestone-summary [version]` + +**Purpose:** Generate comprehensive project summary from milestone artifacts for team onboarding. + +**Requirements:** +- REQ-SUMMARY-01: System MUST aggregate phase plans, summaries, and verification results +- REQ-SUMMARY-02: System MUST work for both current and archived milestones +- REQ-SUMMARY-03: System MUST produce a single navigable document + +**Produces:** +| Artifact | Description | +|----------|-------------| +| `MILESTONE-SUMMARY.md` | Comprehensive navigable summary of milestone artifacts | + +**Process:** +1. **Collect** — Aggregate phase plans, summaries, and verification results from the target milestone +2. **Synthesize** — Combine artifacts into a single navigable document with cross-references +3. **Output** — write `MILESTONE-SUMMARY.md` suitable for team onboarding and stakeholder review + +--- + +### 51. Workstream Namespacing + +**Command:** `/gsd-workstreams` + +**Purpose:** Parallel workstreams for concurrent work on different milestone areas. + +**Requirements:** +- REQ-WS-01: System MUST isolate workstream state in separate `.planning/workstreams/{name}/` directories +- REQ-WS-02: System MUST validate workstream names (alphanumeric + hyphens only, no path traversal) +- REQ-WS-03: System MUST support list, create, switch, status, progress, complete, resume subcommands + +**Produces:** +| Artifact | Description | +|----------|-------------| +| `.planning/workstreams/{name}/` | Isolated workstream directory structure | + +**Process:** +1. **Create** — Initialize a named workstream with isolated `.planning/workstreams/{name}/` directory +2. **Switch** — Change active workstream context for subsequent GSD commands +3. **Manage** — List, check status, track progress, complete, or resume workstreams + +--- + +### 52. Manager Dashboard + +**Command:** `/gsd-manager` + +**Purpose:** Interactive command center for managing multiple phases from one terminal. + +**Requirements:** +- REQ-MGR-01: System MUST show overview of all phases with status +- REQ-MGR-02: System MUST filter to current milestone scope +- REQ-MGR-03: System MUST show phase dependencies and conflicts + +**Produces:** Interactive terminal output + +**Process:** +1. **Scan** — Load all phases in the current milestone with their statuses +2. **Display** — Render overview showing phase dependencies, conflicts, and progress +3. **Interact** — Accept commands to navigate, inspect, or act on individual phases + +--- + +### 53. Assumptions Discussion Mode + +**Command:** `/gsd-discuss-phase` with `workflow.discuss_mode: 'assumptions'` + +**Purpose:** Replace interview-style questioning with codebase-first assumption analysis. + +**Requirements:** +- REQ-ASSUME-01: System MUST analyze codebase to generate structured assumptions before asking questions +- REQ-ASSUME-02: System MUST classify assumptions by confidence level (Confident/Likely/Unclear) +- REQ-ASSUME-03: System MUST produce identical CONTEXT.md format as default discuss mode +- REQ-ASSUME-04: System MUST support confidence-based skip gate (all HIGH = no questions) + +**Produces:** +| Artifact | Description | +|----------|-------------| +| `{phase}-CONTEXT.md` | Same format as default discuss mode | + +**Process:** +1. **Analyze** — Scan codebase to generate structured assumptions about implementation approach +2. **Classify** — Categorize assumptions by confidence level: Confident, Likely, Unclear +3. **Gate** — If all assumptions are HIGH confidence, skip questioning entirely +4. **Confirm** — Present unclear assumptions as targeted questions to the user +5. **Output** — Produce `{phase}-CONTEXT.md` in identical format to default discuss mode + +--- + +### 54. UI Phase Auto-Detection + +**Part of:** `/gsd-new-project` and `/gsd-progress` + +**Purpose:** Automatically detect UI-heavy projects and surface `/gsd-ui-phase` recommendation. + +**Requirements:** +- REQ-UI-DETECT-01: System MUST detect UI signals in project description (keywords, framework references) +- REQ-UI-DETECT-02: System MUST annotate ROADMAP.md phases with `ui_hint` when applicable +- REQ-UI-DETECT-03: System MUST suggest `/gsd-ui-phase` in next steps for UI-heavy phases +- REQ-UI-DETECT-04: System MUST NOT make `/gsd-ui-phase` mandatory + +**Process:** +1. **Detect** — Scan project description and tech stack for UI signals (keywords, framework references) +2. **Annotate** — Add `ui_hint` markers to applicable phases in ROADMAP.md +3. **Surface** — Include `/gsd-ui-phase` recommendation in next steps for UI-heavy phases + +--- + +### 55. Multi-Runtime Installer Selection + +**Part of:** `npx gsd-opencode` + +**Purpose:** Select multiple runtimes in a single interactive install session. + +**Requirements:** +- REQ-MULTI-RT-01: Interactive prompt MUST support multi-select (e.g., OpenCode + Gemini) +- REQ-MULTI-RT-02: CLI flags MUST continue to work for non-interactive installs + +**Process:** +1. **Detect** — Identify available AI CLI runtimes on the system +2. **Prompt** — Present multi-select interface for runtime selection +3. **Install** — Configure GSD for all selected runtimes in a single session diff --git a/gsd-opencode/docs/README.md b/gsd-opencode/docs/README.md new file mode 100644 index 0000000..8fb9b24 --- /dev/null +++ b/gsd-opencode/docs/README.md @@ -0,0 +1,29 @@ +# GSD Documentation + +Comprehensive documentation for the Get Shit Done (GSD) framework — a meta-prompting, context engineering, and spec-driven development system for AI coding agents. + +Language versions: [English](README.md) · [Português (pt-BR)](pt-BR/README.md) · [日本語](ja-JP/README.md) · [简体中文](zh-CN/README.md) + +## Documentation Index + +| Document | Audience | Description | +|----------|----------|-------------| +| [Architecture](ARCHITECTURE.md) | Contributors, advanced users | System architecture, agent model, data flow, and internal design | +| [Feature Reference](FEATURES.md) | All users | Complete feature and function documentation with requirements | +| [Command Reference](COMMANDS.md) | All users | Every command with syntax, flags, options, and examples | +| [Configuration Reference](CONFIGURATION.md) | All users | Full config schema, workflow toggles, model profiles, git branching | +| [CLI Tools Reference](CLI-TOOLS.md) | Contributors, agent authors | `gsd-tools.cjs` programmatic API for workflows and agents | +| [Agent Reference](AGENTS.md) | Contributors, advanced users | All 15 specialized agents — roles, tools, spawn patterns | +| [User Guide](USER-GUIDE.md) | All users | Workflow walkthroughs, troubleshooting, and recovery | +| [Context Monitor](context-monitor.md) | All users | Context window monitoring hook architecture | +| [Discuss Mode](workflow-discuss-mode.md) | All users | Assumptions vs interview mode for discuss-phase | + +## Quick Links + +- **What's new in v1.28:** Forensics, milestone summary, workstreams, assumptions mode, UI auto-detect, manager dashboard +- **Getting started:** [README](../README.md) → install → `/gsd-new-project` +- **Full workflow walkthrough:** [User Guide](USER-GUIDE.md) +- **All commands at a glance:** [Command Reference](COMMANDS.md) +- **Configuring GSD:** [Configuration Reference](CONFIGURATION.md) +- **How the system works internally:** [Architecture](ARCHITECTURE.md) +- **Contributing or extending:** [CLI Tools Reference](CLI-TOOLS.md) + [Agent Reference](AGENTS.md) diff --git a/gsd-opencode/docs/USER-GUIDE.md b/gsd-opencode/docs/USER-GUIDE.md index 72fba23..a4499b6 100644 --- a/gsd-opencode/docs/USER-GUIDE.md +++ b/gsd-opencode/docs/USER-GUIDE.md @@ -7,6 +7,10 @@ A detailed reference for workflows, troubleshooting, and configuration. For quic ## Table of Contents - [Workflow Diagrams](#workflow-diagrams) +- [UI Design Contract](#ui-design-contract) +- [Backlog & Threads](#backlog--threads) +- [Workstreams](#workstreams) +- [Security](#security) - [Command Reference](#command-reference) - [Configuration Reference](#configuration-reference) - [Usage Examples](#usage-examples) @@ -34,6 +38,10 @@ A detailed reference for workflows, troubleshooting, and configuration. For quic │ └──────────┬─────────┘ │ │ │ │ │ ┌──────────▼─────────┐ │ + │ │ /gsd-ui-phase │ │ <- Design contract (frontend) + │ └──────────┬─────────┘ │ + │ │ │ + │ ┌──────────▼─────────┐ │ │ │ /gsd-plan-phase │ │ <- Research + Plan + Verify │ └──────────┬─────────┘ │ │ │ │ @@ -45,6 +53,10 @@ A detailed reference for workflows, troubleshooting, and configuration. For quic │ │ /gsd-verify-work │ │ <- Manual UAT │ └──────────┬─────────┘ │ │ │ │ + │ ┌──────────▼─────────┐ │ + │ │ /gsd-ship │ │ <- Create PR (optional) + │ └──────────┬─────────┘ │ + │ │ │ │ Next Phase?────────────┘ │ │ No └─────────────┼──────────────┘ @@ -146,6 +158,196 @@ escalation for you to address. **When to use:** After executing phases that were planned before Nyquist was enabled, or after `/gsd-audit-milestone` surfaces Nyquist compliance gaps. +### Assumptions Discussion Mode + +By default, `/gsd-discuss-phase` asks open-ended questions about your implementation preferences. Assumptions mode inverts this: GSD reads your codebase first, surfaces structured assumptions about how it would build the phase, and asks only for corrections. + +**Enable:** Set `workflow.discuss_mode` to `'assumptions'` via `/gsd-settings`. + +**How it works:** +1. Reads PROJECT.md, codebase mapping, and existing conventions +2. Generates a structured list of assumptions (tech choices, patterns, file locations) +3. Presents assumptions for you to confirm, correct, or expand +4. Writes CONTEXT.md from confirmed assumptions + +**When to use:** +- Experienced developers who already know their codebase well +- Rapid iteration where open-ended questions slow you down +- Projects where patterns are well-established and predictable + +See [docs/workflow-discuss-mode.md](workflow-discuss-mode.md) for the full discuss-mode reference. + +--- + +## UI Design Contract + +### Why + +AI-generated frontends are visually inconsistent not because OpenCode is bad at UI but because no design contract existed before execution. Five components built without a shared spacing scale, color contract, or copywriting standard produce five slightly different visual decisions. + +`/gsd-ui-phase` locks the design contract before planning. `/gsd-ui-review` audits the result after execution. + +### Commands + +| Command | Description | +|---------|-------------| +| `/gsd-ui-phase [N]` | Generate UI-SPEC.md design contract for a frontend phase | +| `/gsd-ui-review [N]` | Retroactive 6-pillar visual audit of implemented UI | + +### Workflow: `/gsd-ui-phase` + +**When to run:** After `/gsd-discuss-phase`, before `/gsd-plan-phase` — for phases with frontend/UI work. + +**Flow:** +1. Reads CONTEXT.md, RESEARCH.md, REQUIREMENTS.md for existing decisions +2. Detects design system state (shadcn components.json, Tailwind config, existing tokens) +3. shadcn initialization gate — offers to initialize if React/Next.js/Vite project has none +4. Asks only unanswered design contract questions (spacing, typography, color, copywriting, registry safety) +5. Writes `{phase}-UI-SPEC.md` to phase directory +6. Validates against 6 dimensions (Copywriting, Visuals, Color, Typography, Spacing, Registry Safety) +7. Revision loop if BLOCKED (max 2 iterations) + +**Output:** `{padded_phase}-UI-SPEC.md` in `.planning/phases/{phase-dir}/` + +### Workflow: `/gsd-ui-review` + +**When to run:** After `/gsd-execute-phase` or `/gsd-verify-work` — for any project with frontend code. + +**Standalone:** Works on any project, not just GSD-managed ones. If no UI-SPEC.md exists, audits against abstract 6-pillar standards. + +**6 Pillars (scored 1-4 each):** +1. Copywriting — CTA labels, empty states, error states +2. Visuals — focal points, visual hierarchy, icon accessibility +3. Color — accent usage discipline, 60/30/10 compliance +4. Typography — font size/weight constraint adherence +5. Spacing — grid alignment, token consistency +6. Experience Design — loading/error/empty state coverage + +**Output:** `{padded_phase}-UI-REVIEW.md` in phase directory with scores and top 3 priority fixes. + +### Configuration + +| Setting | Default | Description | +|---------|---------|-------------| +| `workflow.ui_phase` | `true` | Generate UI design contracts for frontend phases | +| `workflow.ui_safety_gate` | `true` | plan-phase prompts to run /gsd-ui-phase for frontend phases | + +Both follow the absent=enabled pattern. Disable via `/gsd-settings`. + +### shadcn Initialization + +For React/Next.js/Vite projects, the UI researcher offers to initialize shadcn if no `components.json` is found. The flow: + +1. Visit `ui.shadcn.com/create` and configure your preset +2. Copy the preset string +3. Run `npx shadcn init --preset {paste}` +4. Preset encodes the entire design system — colors, border radius, fonts + +The preset string becomes a first-class GSD planning artifact, reproducible across phases and milestones. + +### Registry Safety Gate + +Third-party shadcn registries can inject arbitrary code. The safety gate requires: +- `npx shadcn view {component}` — inspect before installing +- `npx shadcn diff {component}` — compare against official + +Controlled by `workflow.ui_safety_gate` config toggle. + +### Screenshot Storage + +`/gsd-ui-review` captures screenshots via Playwright CLI to `.planning/ui-reviews/`. A `.gitignore` is created automatically to prevent binary files from reaching git. Screenshots are cleaned up during `/gsd-complete-milestone`. + +--- + +## Backlog & Threads + +### Backlog Parking Lot + +Ideas that aren't ready for active planning go into the backlog using 999.x numbering, keeping them outside the active phase sequence. + +``` +/gsd-add-backlog "GraphQL API layer" # Creates 999.1-graphql-api-layer/ +/gsd-add-backlog "Mobile responsive" # Creates 999.2-mobile-responsive/ +``` + +Backlog items get full phase directories, so you can use `/gsd-discuss-phase 999.1` to explore an idea further or `/gsd-plan-phase 999.1` when it's ready. + +**Review and promote** with `/gsd-review-backlog` — it shows all backlog items and lets you promote (move to active sequence), keep (leave in backlog), or remove (delete). + +### Seeds + +Seeds are forward-looking ideas with trigger conditions. Unlike backlog items, seeds surface automatically when the right milestone arrives. + +``` +/gsd-plant-seed "Add real-time collab when WebSocket infra is in place" +``` + +Seeds preserve the full WHY and WHEN to surface. `/gsd-new-milestone` scans all seeds and presents matches. + +**Storage:** `.planning/seeds/SEED-NNN-slug.md` + +### Persistent Context Threads + +Threads are lightweight cross-session knowledge stores for work that spans multiple sessions but doesn't belong to any specific phase. + +``` +/gsd-thread # List all threads +/gsd-thread fix-deploy-key-auth # Resume existing thread +/gsd-thread "Investigate TCP timeout" # Create new thread +``` + +Threads are lighter weight than `/gsd-pause-work` — no phase state, no plan context. Each thread file includes Goal, Context, References, and Next Steps sections. + +Threads can be promoted to phases (`/gsd-add-phase`) or backlog items (`/gsd-add-backlog`) when they mature. + +**Storage:** `.planning/threads/{slug}.md` + +--- + +## Workstreams + +Workstreams let you work on multiple milestone areas concurrently without state collisions. Each workstream gets its own isolated `.planning/` state, so switching between them doesn't clobber progress. + +**When to use:** You're working on milestone features that span different concern areas (e.g., backend API and frontend dashboard) and want to plan, execute, or discuss them independently without context bleed. + +### Commands + +| Command | Purpose | +|---------|---------| +| `/gsd-workstreams create ` | Create a new workstream with isolated planning state | +| `/gsd-workstreams switch ` | Switch active context to a different workstream | +| `/gsd-workstreams list` | Show all workstreams and which is active | +| `/gsd-workstreams complete ` | Mark a workstream as done and archive its state | + +### How It Works + +Each workstream maintains its own `.planning/` directory subtree. When you switch workstreams, GSD swaps the active planning context so that `/gsd-progress`, `/gsd-discuss-phase`, `/gsd-plan-phase`, and other commands operate on that workstream's state. + +This is lighter weight than `/gsd-new-workspace` (which creates separate repo worktrees). Workstreams share the same codebase and git history but isolate planning artifacts. + +--- + +## Security + +### Defense-in-Depth (v1.27) + +GSD generates markdown files that become LLM system prompts. This means any user-controlled text flowing into planning artifacts is a potential indirect prompt injection vector. v1.27 introduced centralized security hardening: + +**Path Traversal Prevention:** +All user-supplied file paths (`--text-file`, `--prd`) are validated to resolve within the project directory. macOS `/var` → `/private/var` symlink resolution is handled. + +**Prompt Injection Detection:** +The `security.cjs` module scans for known injection patterns (role overrides, instruction bypasses, system tag injections) in user-supplied text before it enters planning artifacts. + +**Runtime Hooks:** +- `gsd-prompt-guard.js` — Scans write/edit calls to `.planning/` for injection patterns (always active, advisory-only) +- `gsd-workflow-guard.js` — Warns on file edits outside GSD workflow context (opt-in via `hooks.workflow_guard`) + +**CI Scanner:** +`prompt-injection-scan.test.cjs` scans all agent, workflow, and command files for embedded injection vectors. Run as part of the test suite. + +--- + ### Execution Wave Coordination ``` @@ -193,9 +395,14 @@ enabled, or after `/gsd-audit-milestone` surfaces Nyquist compliance gaps. | `/gsd-new-project` | Full project init: questions, research, requirements, roadmap | Start of a new project | | `/gsd-new-project --auto @idea.md` | Automated init from document | Have a PRD or idea doc ready | | `/gsd-discuss-phase [N]` | Capture implementation decisions | Before planning, to shape how it gets built | +| `/gsd-ui-phase [N]` | Generate UI design contract | After discuss-phase, before plan-phase (frontend phases) | | `/gsd-plan-phase [N]` | Research + plan + verify | Before executing a phase | | `/gsd-execute-phase ` | Execute all plans in parallel waves | After planning is complete | | `/gsd-verify-work [N]` | Manual UAT with auto-diagnosis | After execution completes | +| `/gsd-ship [N]` | Create PR from verified work | After verification passes | +| `/gsd-fast ` | Inline trivial tasks — skips planning entirely | Typo fixes, config changes, small refactors | +| `/gsd-next` | Auto-detect state and run next step | Anytime — "what should I do next?" | +| `/gsd-ui-review [N]` | Retroactive 6-pillar visual audit | After execution or verify-work (frontend projects) | | `/gsd-audit-milestone` | Verify milestone met its definition of done | Before completing milestone | | `/gsd-complete-milestone` | Archive milestone, tag release | All phases verified | | `/gsd-new-milestone [name]` | Start next version cycle | After completing a milestone | @@ -206,7 +413,8 @@ enabled, or after `/gsd-audit-milestone` surfaces Nyquist compliance gaps. |---------|---------|-------------| | `/gsd-progress` | Show status and next steps | Anytime -- "where am I?" | | `/gsd-resume-work` | Restore full context from last session | Starting a new session | -| `/gsd-pause-work` | Save context handoff | Stopping mid-phase | +| `/gsd-pause-work` | Save structured handoff (HANDOFF.json + continue-here.md) | Stopping mid-phase | +| `/gsd-session-report` | Generate session summary with work and outcomes | End of session, stakeholder sharing | | `/gsd-help` | Show all commands | Quick reference | | `/gsd-update` | Update GSD with changelog preview | Check for new versions | | `/gsd-join-discord` | Open Discord community invite | Questions or community | @@ -229,12 +437,30 @@ enabled, or after `/gsd-audit-milestone` surfaces Nyquist compliance gaps. | `/gsd-map-codebase` | Analyze existing codebase | Before `/gsd-new-project` on existing code | | `/gsd-quick` | Ad-hoc task with GSD guarantees | Bug fixes, small features, config changes | | `/gsd-debug [desc]` | Systematic debugging with persistent state | When something breaks | +| `/gsd-forensics` | Diagnostic report for workflow failures | When state, artifacts, or git history seem corrupted | | `/gsd-add-todo [desc]` | Capture an idea for later | Think of something during a session | | `/gsd-check-todos` | List pending todos | Review captured ideas | | `/gsd-settings` | Configure workflow toggles and model profile | Change model, toggle agents | | `/gsd-set-profile ` | Quick profile switch | Change cost/quality tradeoff | | `/gsd-reapply-patches` | Restore local modifications after update | After `/gsd-update` if you had local edits | +### Code Quality & Review + +| Command | Purpose | When to Use | +|---------|---------|-------------| +| `/gsd-review --phase N` | Cross-AI peer review from external CLIs | Before executing, to validate plans | +| `/gsd-pr-branch` | Clean PR branch filtering `.planning/` commits | Before creating PR with planning-free diff | +| `/gsd-audit-uat` | Audit verification debt across all phases | Before milestone completion | + +### Backlog & Threads + +| Command | Purpose | When to Use | +|---------|---------|-------------| +| `/gsd-add-backlog ` | Add idea to backlog parking lot (999.x) | Ideas not ready for active planning | +| `/gsd-review-backlog` | Promote/keep/remove backlog items | Before new milestone, to prioritize | +| `/gsd-plant-seed ` | Forward-looking idea with trigger conditions | Ideas that should surface at a future milestone | +| `/gsd-thread [name]` | Persistent context threads | Cross-session work outside the phase structure | + --- ## Configuration Reference @@ -256,12 +482,23 @@ GSD stores project settings in `.planning/config.json`. Configure during `/gsd-n "research": true, "plan_check": true, "verifier": true, - "nyquist_validation": true + "nyquist_validation": true, + "ui_phase": true, + "ui_safety_gate": true, + "research_before_questions": false, + "discuss_mode": "standard", + "skip_discuss": false + }, + "resolve_model_ids": "anthropic", + "hooks": { + "context_warnings": true, + "workflow_guard": false }, "git": { "branching_strategy": "none", "phase_branch_template": "gsd/phase-{phase}-{slug}", - "milestone_branch_template": "gsd/{milestone}-{slug}" + "milestone_branch_template": "gsd/{milestone}-{slug}", + "quick_branch_template": null } } ``` @@ -272,7 +509,7 @@ GSD stores project settings in `.planning/config.json`. Configure during `/gsd-n |---------|---------|---------|------------------| | `mode` | `interactive`, `yolo` | `interactive` | `yolo` auto-approves decisions; `interactive` confirms at each step | | `granularity` | `coarse`, `standard`, `fine` | `standard` | Phase granularity: how finely scope is sliced (3-5, 5-8, or 8-12 phases) | -| `model_profile` | `quality`, `balanced`, `budget` | `balanced` | Model tier for each agent (see table below) | +| `model_profile` | `quality`, `balanced`, `budget`, `inherit` | `balanced` | Model tier for each agent (see table below) | ### Planning Settings @@ -291,8 +528,20 @@ GSD stores project settings in `.planning/config.json`. Configure during `/gsd-n | `workflow.plan_check` | `true`, `false` | `true` | Plan verification loop (up to 3 iterations) | | `workflow.verifier` | `true`, `false` | `true` | Post-execution verification against phase goals | | `workflow.nyquist_validation` | `true`, `false` | `true` | Validation architecture research during plan-phase; 8th plan-check dimension | +| `workflow.ui_phase` | `true`, `false` | `true` | Generate UI design contracts for frontend phases | +| `workflow.ui_safety_gate` | `true`, `false` | `true` | plan-phase prompts to run /gsd-ui-phase for frontend phases | +| `workflow.research_before_questions` | `true`, `false` | `false` | Run research before discussion questions instead of after | +| `workflow.discuss_mode` | `standard`, `assumptions` | `standard` | Discussion style: open-ended questions vs. codebase-driven assumptions | +| `workflow.skip_discuss` | `true`, `false` | `false` | Skip discuss-phase entirely in autonomous mode; writes minimal CONTEXT.md from ROADMAP phase goal | -Disable these to speed up phases in familiar domains or when conserving tokens. +### Hook Settings + +| Setting | Options | Default | What it Controls | +|---------|---------|---------|------------------| +| `hooks.context_warnings` | `true`, `false` | `true` | Context window usage warnings | +| `hooks.workflow_guard` | `true`, `false` | `false` | Warn on file edits outside GSD workflow context | + +Disable workflow toggles to speed up phases in familiar domains or when conserving tokens. ### Git Branching @@ -301,6 +550,7 @@ Disable these to speed up phases in familiar domains or when conserving tokens. | `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | When and how branches are created | | `git.phase_branch_template` | Template string | `gsd/phase-{phase}-{slug}` | Branch name for phase strategy | | `git.milestone_branch_template` | Template string | `gsd/{milestone}-{slug}` | Branch name for milestone strategy | +| `git.quick_branch_template` | Template string or `null` | `null` | Optional branch name for `/gsd-quick` tasks | **Branching strategies explained:** @@ -310,28 +560,37 @@ Disable these to speed up phases in familiar domains or when conserving tokens. | `phase` | At each `execute-phase` | One phase per branch | Code review per phase, granular rollback | | `milestone` | At first `execute-phase` | All phases share one branch | Release branches, PR per version | -**Template variables:** `{phase}` = zero-padded number (e.g., "03"), `{slug}` = lowercase hyphenated name, `{milestone}` = version (e.g., "v1.0"). +**Template variables:** `{phase}` = zero-padded number (e.g., "03"), `{slug}` = lowercase hyphenated name, `{milestone}` = version (e.g., "v1.0"), `{num}` / `{quick}` = quick task ID (e.g., "260317-abc"). + +Example quick-task branching: + +```json +"git": { + "quick_branch_template": "gsd/quick-{num}-{slug}" +} +``` ### Model Profiles (Per-Agent Breakdown) -| Agent | `quality` | `balanced` | `budget` | -|-------|-----------|------------|----------| -| gsd-planner | Opus | Opus | Sonnet | -| gsd-roadmapper | Opus | Sonnet | Sonnet | -| gsd-executor | Opus | Sonnet | Sonnet | -| gsd-phase-researcher | Opus | Sonnet | Haiku | -| gsd-project-researcher | Opus | Sonnet | Haiku | -| gsd-research-synthesizer | Sonnet | Sonnet | Haiku | -| gsd-debugger | Opus | Sonnet | Sonnet | -| gsd-codebase-mapper | Sonnet | Haiku | Haiku | -| gsd-verifier | Sonnet | Sonnet | Haiku | -| gsd-plan-checker | Sonnet | Sonnet | Haiku | -| gsd-integration-checker | Sonnet | Sonnet | Haiku | +| Agent | `quality` | `balanced` | `budget` | `inherit` | +|-------|-----------|------------|----------|-----------| +| gsd-planner | Opus | Opus | Sonnet | Inherit | +| gsd-roadmapper | Opus | Sonnet | Sonnet | Inherit | +| gsd-executor | Opus | Sonnet | Sonnet | Inherit | +| gsd-phase-researcher | Opus | Sonnet | Haiku | Inherit | +| gsd-project-researcher | Opus | Sonnet | Haiku | Inherit | +| gsd-research-synthesizer | Sonnet | Sonnet | Haiku | Inherit | +| gsd-debugger | Opus | Sonnet | Sonnet | Inherit | +| gsd-codebase-mapper | Sonnet | Haiku | Haiku | Inherit | +| gsd-verifier | Sonnet | Sonnet | Haiku | Inherit | +| gsd-plan-checker | Sonnet | Sonnet | Haiku | Inherit | +| gsd-integration-checker | Sonnet | Sonnet | Haiku | Inherit | **Profile philosophy:** - **quality** -- Opus for all decision-making agents, Sonnet for read-only verification. Use when quota is available and the work is critical. - **balanced** -- Opus only for planning (where architecture decisions happen), Sonnet for everything else. The default for good reason. - **budget** -- Sonnet for anything that writes code, Haiku for research and verification. Use for high-volume work or less critical phases. +- **inherit** -- All agents use the current session model. Best when switching models dynamically (e.g. OpenCode `/model`), or when using OpenCode with non-Anthropic providers (OpenRouter, local models) to avoid unexpected API costs. For non-OpenCode runtimes (Codex, OpenCode, Gemini CLI), the installer sets `resolve_model_ids: "omit"` automatically -- see [Non-OpenCode Runtimes](#using-non-OpenCode-runtimes-codex-opencode-gemini-cli). --- @@ -344,14 +603,18 @@ OpenCode --dangerously-skip-permissions /gsd-new-project # Answer questions, configure, approve roadmap /new /gsd-discuss-phase 1 # Lock in your preferences +/gsd-ui-phase 1 # Design contract (frontend phases) /gsd-plan-phase 1 # Research + plan + verify /gsd-execute-phase 1 # Parallel execution /gsd-verify-work 1 # Manual UAT +/gsd-ship 1 # Create PR from verified work +/gsd-ui-review 1 # Visual audit (frontend phases) /new -/gsd-discuss-phase 2 # Repeat for each phase +/gsd-next # Auto-detect and run next step ... /gsd-audit-milestone # Check everything shipped /gsd-complete-milestone # Archive, tag, done +/gsd-session-report # Generate session summary ``` ### New Project from Existing Document @@ -401,6 +664,8 @@ OpenCode --dangerously-skip-permissions | Normal dev | `interactive` | `standard` | `balanced` | on | on | on | | Production | `interactive` | `fine` | `quality` | on | on | on | +**Skipping discuss-phase in autonomous mode:** When running in `yolo` mode with well-established preferences already captured in PROJECT.md, set `workflow.skip_discuss: true` via `/gsd-settings`. This bypasses the discuss-phase entirely and writes a minimal CONTEXT.md derived from the ROADMAP phase goal. Useful when your PROJECT.md and conventions are comprehensive enough that discussion adds no new information. + ### Mid-Milestone Scope Changes ```bash @@ -411,6 +676,31 @@ OpenCode --dangerously-skip-permissions /gsd-remove-phase 7 # Descope phase 7 and renumber ``` +### Multi-Project Workspaces + +Work on multiple repos or features in parallel with isolated GSD state. + +```bash +# Create a workspace with repos from your monorepo +/gsd-new-workspace --name feature-b --repos hr-ui,ZeymoAPI + +# Feature branch isolation — worktree of current repo with its own .planning/ +/gsd-new-workspace --name feature-b --repos . + +# Then cd into the workspace and initialize GSD +cd ~/gsd-workspaces/feature-b +/gsd-new-project + +# List and manage workspaces +/gsd-list-workspaces +/gsd-remove-workspace feature-b +``` + +Each workspace gets: +- Its own `.planning/` directory (fully independent from source repos) +- Git worktrees (default) or clones of specified repos +- A `WORKSPACE.md` manifest tracking member repos + --- ## Troubleshooting @@ -443,6 +733,31 @@ Do not re-run `/gsd-execute-phase`. Use `/gsd-quick` for targeted fixes, or `/gs Switch to budget profile: `/gsd-set-profile budget`. Disable research and plan-check agents via `/gsd-settings` if the domain is familiar to you (or to OpenCode). +### Using Non-OpenCode Runtimes (Codex, OpenCode, Gemini CLI) + +If you installed GSD for a non-OpenCode runtime, the installer already configured model resolution so all agents use the runtime's default model. No manual setup is needed. Specifically, the installer sets `resolve_model_ids: "omit"` in your config, which tells GSD to skip Anthropic model ID resolution and let the runtime choose its own default model. + +To assign different models to different agents on a non-OpenCode runtime, add `model_overrides` to `.planning/config.json` with fully-qualified model IDs that your runtime recognizes: + +```json +{ + "resolve_model_ids": "omit", + "model_overrides": { + "gsd-planner": "o3", + "gsd-executor": "o4-mini", + "gsd-debugger": "o3" + } +} +``` + +The installer auto-configures `resolve_model_ids: "omit"` for Gemini CLI, OpenCode, and Codex. If you're manually setting up a non-OpenCode runtime, add it to `.planning/config.json` yourself. + +See the [Configuration Reference](CONFIGURATION.md#non-OpenCode-runtimes-codex-opencode-gemini-cli) for the full explanation. + +### Using OpenCode with Non-Anthropic Providers (OpenRouter, Local) + +If GSD subagents call Anthropic models and you're paying through OpenRouter or a local provider, switch to the `inherit` profile: `/gsd-set-profile inherit`. This makes all agents use your current session model instead of specific Anthropic models. See also `/gsd-settings` → Model Profile → Inherit. + ### Working on a Sensitive/Private Project Set `commit_docs: false` during `/gsd-new-project` or via `/gsd-settings`. Add `.planning/` to your `.gitignore`. Planning artifacts stay local and never touch git. @@ -451,10 +766,36 @@ Set `commit_docs: false` during `/gsd-new-project` or via `/gsd-settings`. Add ` Since v1.17, the installer backs up locally modified files to `gsd-local-patches/`. Run `/gsd-reapply-patches` to merge your changes back. +### Workflow Diagnostics (`/gsd-forensics`) + +When a workflow fails in a way that isn't obvious -- plans reference nonexistent files, execution produces unexpected results, or state seems corrupted -- run `/gsd-forensics` to generate a diagnostic report. + +**What it checks:** +- Git history anomalies (orphaned commits, unexpected branch state, rebase artifacts) +- Artifact integrity (missing or malformed planning files, broken cross-references) +- State inconsistencies (ROADMAP status vs. actual file presence, config drift) + +**Output:** A diagnostic report written to `.planning/forensics/` with findings and suggested remediation steps. + ### Subagent Appears to Fail but Work Was Done A known workaround exists for a OpenCode classification bug. GSD's orchestrators (execute-phase, quick) spot-check actual output before reporting failure. If you see a failure message but commits were made, check `git log` -- the work may have succeeded. +### Parallel Execution Causes Build Lock Errors + +If you see pre-commit hook failures, cargo lock contention, or 30+ minute execution times during parallel wave execution, this is caused by multiple agents triggering build tools simultaneously. GSD handles this automatically since v1.26 — parallel agents use `--no-verify` on commits and the orchestrator runs hooks once after each wave. If you're on an older version, add this to your project's `AGENTS.md`: + +```markdown +## Git Commit Rules for Agents +All subagent/executor commits MUST use `--no-verify`. +``` + +To disable parallel execution entirely: `/gsd-settings` → set `parallelization.enabled` to `false`. + +### Windows: Installation Crashes on Protected Directories + +If the installer crashes with `EPERM: operation not permitted, scandir` on Windows, this is caused by OS-protected directories (e.g., Chromium browser profiles). Fixed since v1.24 — update to the latest version. As a workaround, temporarily rename the problematic directory before running the installer. + --- ## Recovery Quick Reference @@ -466,10 +807,14 @@ A known workaround exists for a OpenCode classification bug. GSD's orchestrators | Need to change scope | `/gsd-add-phase`, `/gsd-insert-phase`, or `/gsd-remove-phase` | | Milestone audit found gaps | `/gsd-plan-milestone-gaps` | | Something broke | `/gsd-debug "description"` | +| Workflow state seems corrupted | `/gsd-forensics` | | Quick targeted fix | `/gsd-quick` | | Plan doesn't match your vision | `/gsd-discuss-phase [N]` then re-plan | | Costs running high | `/gsd-set-profile budget` and `/gsd-settings` to toggle agents off | | Update broke local changes | `/gsd-reapply-patches` | +| Want session summary for stakeholder | `/gsd-session-report` | +| Don't know what step is next | `/gsd-next` | +| Parallel execution build errors | Update GSD or set `parallelization.enabled: false` | --- @@ -485,7 +830,9 @@ For reference, here is what GSD creates in your project: STATE.md # Decisions, blockers, session memory config.json # Workflow configuration MILESTONES.md # Completed milestone archive + HANDOFF.json # Structured session handoff (from /gsd-pause-work) research/ # Domain research from /gsd-new-project + reports/ # Session reports (from /gsd-session-report) todos/ pending/ # Captured ideas awaiting work done/ # Completed todos @@ -499,4 +846,7 @@ For reference, here is what GSD creates in your project: CONTEXT.md # Your implementation preferences RESEARCH.md # Ecosystem research findings VERIFICATION.md # Post-execution verification results + XX-UI-SPEC.md # UI design contract (from /gsd-ui-phase) + XX-UI-REVIEW.md # Visual audit scores (from /gsd-ui-review) + ui-reviews/ # Screenshots from /gsd-ui-review (gitignored) ``` diff --git a/gsd-opencode/docs/ja-JP/AGENTS.md b/gsd-opencode/docs/ja-JP/AGENTS.md new file mode 100644 index 0000000..d880e2b --- /dev/null +++ b/gsd-opencode/docs/ja-JP/AGENTS.md @@ -0,0 +1,428 @@ +# GSD エージェントリファレンス + +> 全18種の専門エージェント — 役割、ツール、スポーンパターン、相互関係。アーキテクチャの詳細は[アーキテクチャ](ARCHITECTURE.md)を参照してください。 + +--- + +## 概要 + +GSD はマルチエージェントアーキテクチャを採用しており、軽量なオーケストレーター（ワークフローファイル）が新しいコンテキストウィンドウを持つ専門エージェントをスポーンします。各エージェントは特定の役割に特化し、限定的なツールアクセス権を持ち、特定の成果物を生成します。 + +### エージェントカテゴリ + +| カテゴリ | 数 | エージェント | +|----------|-----|-------------| +| リサーチャー | 3 | project-researcher, phase-researcher, ui-researcher | +| アナライザー | 2 | assumptions-analyzer, advisor-researcher | +| シンセサイザー | 1 | research-synthesizer | +| プランナー | 1 | planner | +| ロードマッパー | 1 | roadmapper | +| エグゼキューター | 1 | executor | +| チェッカー | 3 | plan-checker, integration-checker, ui-checker | +| ベリファイヤー | 1 | verifier | +| オーディター | 2 | nyquist-auditor, ui-auditor | +| マッパー | 1 | codebase-mapper | +| デバッガー | 1 | debugger | + +--- + +## エージェント詳細 + +### gsd-project-researcher + +**役割:** ロードマップ作成前にドメインエコシステムを調査する。 + +| プロパティ | 値 | +|------------|-----| +| **スポーン元** | `/gsd-new-project`, `/gsd-new-milestone` | +| **並列数** | 4インスタンス（stack, features, architecture, pitfalls） | +| **ツール** | read, write, bash, grep, glob, websearch, webfetch, mcp (context7) | +| **モデル (balanced)** | Sonnet | +| **生成物** | `.planning/research/STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md` | + +**機能:** +- Web検索による最新のエコシステム情報の取得 +- Context7 MCP統合によるライブラリドキュメントの参照 +- リサーチドキュメントを直接ディスクに書き込み（オーケストレーターのコンテキスト負荷を軽減） + +--- + +### gsd-phase-researcher + +**役割:** 計画策定前に、特定フェーズの実装方法を調査する。 + +| プロパティ | 値 | +|------------|-----| +| **スポーン元** | `/gsd-plan-phase` | +| **並列数** | 4インスタンス（project-researcher と同じフォーカスエリア） | +| **ツール** | read, write, bash, grep, glob, websearch, webfetch, mcp (context7) | +| **モデル (balanced)** | Sonnet | +| **生成物** | `{phase}-RESEARCH.md` | + +**機能:** +- CONTEXT.md を読み取り、ユーザーの決定事項に焦点を当てた調査を実施 +- 特定フェーズのドメインに対する実装パターンの調査 +- Nyquist バリデーションマッピング用のテストインフラの検出 + +--- + +### gsd-ui-researcher + +**役割:** フロントエンドフェーズ向けのUIデザインコントラクトを作成する。 + +| プロパティ | 値 | +|------------|-----| +| **スポーン元** | `/gsd-ui-phase` | +| **並列数** | 単一インスタンス | +| **ツール** | read, write, bash, grep, glob, websearch, webfetch, mcp (context7) | +| **モデル (balanced)** | Sonnet | +| **カラー** | `#E879F9`（フクシア） | +| **生成物** | `{phase}-UI-SPEC.md` | + +**機能:** +- デザインシステムの状態を検出（shadcn の components.json、Tailwind 設定、既存トークン） +- React/Next.js/Vite プロジェクト向けの shadcn 初期化を提案 +- 未回答のデザインコントラクトに関する質問のみを提示 +- サードパーティコンポーネントに対するレジストリ安全ゲートの適用 + +--- + +### gsd-assumptions-analyzer + +**役割:** フェーズに対してコードベースを深く分析し、エビデンス・信頼度・誤った場合の影響を含む構造化された前提条件を返す。 + +| プロパティ | 値 | +|------------|-----| +| **スポーン元** | `discuss-phase-assumptions` ワークフロー（`workflow.discuss_mode = 'assumptions'` の場合） | +| **並列数** | 単一インスタンス | +| **ツール** | read, bash, grep, glob | +| **モデル (balanced)** | Sonnet | +| **カラー** | Cyan | +| **生成物** | 決定ステートメント、エビデンスファイルパス、信頼度レベルを含む構造化された前提条件 | + +**主な動作:** +- ROADMAP.md のフェーズ説明と過去の CONTEXT.md ファイルを読み取り +- フェーズに関連するファイル（コンポーネント、パターン、類似機能）をコードベースから検索 +- エビデンスに基づく前提条件を形成するため、最も関連性の高いソースファイルを5〜15件読み取り +- 信頼度の分類: Confident（コードから明確）、Likely（妥当な推論）、Unclear（複数の方向性がありうる） +- 外部調査が必要なトピック（ライブラリ互換性、エコシステムのベストプラクティス）にフラグを付与 +- ティアによる出力の調整: full_maturity（3〜5領域）、standard（3〜4）、minimal_decisive（2〜3） + +--- + +### gsd-advisor-researcher + +**役割:** discuss-phase のアドバイザーモードにおいて、単一のグレーエリアの決定事項を調査し、構造化された比較表を返す。 + +| プロパティ | 値 | +|------------|-----| +| **スポーン元** | `discuss-phase` ワークフロー（ADVISOR_MODE = true の場合） | +| **並列数** | 複数インスタンス（グレーエリアごとに1つ） | +| **ツール** | read, bash, grep, glob, websearch, webfetch, mcp (context7) | +| **モデル (balanced)** | Sonnet | +| **カラー** | Cyan | +| **生成物** | 根拠パラグラフ付きの5列比較表（Option / Pros / Cons / Complexity / Recommendation） | + +**主な動作:** +- OpenCode の知識、Context7、Web検索を使用して、割り当てられた単一のグレーエリアを調査 +- 実質的に有効な選択肢を提示 — 水増しのための代替案は含めない +- Complexity 列は影響範囲+リスクで表記（時間見積もりは使用しない） +- 推奨は条件付き（「Xの場合は推奨」「Yの場合は推奨」）— 単一の勝者ランキングにはしない +- ティアによる出力の調整: full_maturity（成熟度シグナル付き3〜5選択肢）、standard（2〜4）、minimal_decisive（2選択肢、決定的な推奨） + +--- + +### gsd-research-synthesizer + +**役割:** 並列リサーチャーの出力を統合サマリーにまとめる。 + +| プロパティ | 値 | +|------------|-----| +| **スポーン元** | `/gsd-new-project`（4つのリサーチャー完了後） | +| **並列数** | 単一インスタンス（リサーチャー後に順次実行） | +| **ツール** | read, write, bash | +| **モデル (balanced)** | Sonnet | +| **カラー** | Purple | +| **生成物** | `.planning/research/SUMMARY.md` | + +--- + +### gsd-planner + +**役割:** タスク分解、依存関係分析、ゴール逆算検証を含む実行可能なフェーズ計画を作成する。 + +| プロパティ | 値 | +|------------|-----| +| **スポーン元** | `/gsd-plan-phase`, `/gsd-quick` | +| **並列数** | 単一インスタンス | +| **ツール** | read, write, bash, glob, grep, webfetch, mcp (context7) | +| **モデル (balanced)** | Opus | +| **カラー** | Green | +| **生成物** | `{phase}-{N}-PLAN.md` ファイル | + +**主な動作:** +- PROJECT.md、REQUIREMENTS.md、CONTEXT.md、RESEARCH.md を読み取り +- 単一のコンテキストウィンドウに収まるサイズの原子的タスク計画を2〜3個作成 +- `` 要素を含むXML構造を使用 +- `read_first` および `acceptance_criteria` セクションを含む +- 計画を依存関係のウェーブにグループ化 + +--- + +### gsd-roadmapper + +**役割:** フェーズ分解と要件マッピングを含むプロジェクトロードマップを作成する。 + +| プロパティ | 値 | +|------------|-----| +| **スポーン元** | `/gsd-new-project` | +| **並列数** | 単一インスタンス | +| **ツール** | read, write, bash, glob, grep | +| **モデル (balanced)** | Sonnet | +| **カラー** | Purple | +| **生成物** | `ROADMAP.md` | + +**主な動作:** +- 要件をフェーズにマッピング（トレーサビリティ） +- 要件から成功基準を導出 +- 粒度設定に基づくフェーズ数の調整 +- カバレッジの検証（すべての v1 要件がフェーズにマッピングされていること） + +--- + +### gsd-executor + +**役割:** アトミックコミット、逸脱処理、チェックポイントプロトコルを使用して GSD 計画を実行する。 + +| プロパティ | 値 | +|------------|-----| +| **スポーン元** | `/gsd-execute-phase`, `/gsd-quick` | +| **並列数** | 複数（ウェーブ内は並列、ウェーブ間は順次） | +| **ツール** | read, write, edit, bash, grep, glob | +| **モデル (balanced)** | Sonnet | +| **カラー** | Yellow | +| **生成物** | コード変更、git コミット、`{phase}-{N}-SUMMARY.md` | + +**主な動作:** +- 計画ごとに新しい200Kコンテキストウィンドウを使用 +- XMLタスク指示に正確に従う +- 完了したタスクごとにアトミックな git コミットを作成 +- チェックポイントタイプの処理: auto, human-verify, decision, human-action +- 計画からの逸脱を SUMMARY.md に報告 +- 検証失敗時にノードリペアを実行 + +--- + +### gsd-plan-checker + +**役割:** 実行前に計画がフェーズ目標を達成できるかを検証する。 + +| プロパティ | 値 | +|------------|-----| +| **スポーン元** | `/gsd-plan-phase`（検証ループ、最大3回の反復） | +| **並列数** | 単一インスタンス（反復型） | +| **ツール** | read, bash, glob, grep | +| **モデル (balanced)** | Sonnet | +| **カラー** | Green | +| **生成物** | 具体的なフィードバック付きの PASS/FAIL 判定 | + +**8つの検証ディメンション:** +1. 要件カバレッジ +2. タスクの原子性 +3. 依存関係の順序 +4. ファイルスコープ +5. 検証コマンド +6. コンテキスト適合性 +7. ギャップ検出 +8. Nyquist コンプライアンス（有効時） + +--- + +### gsd-integration-checker + +**役割:** フェーズ間の統合とエンドツーエンドフローを検証する。 + +| プロパティ | 値 | +|------------|-----| +| **スポーン元** | `/gsd-audit-milestone` | +| **並列数** | 単一インスタンス | +| **ツール** | read, bash, grep, glob | +| **モデル (balanced)** | Sonnet | +| **カラー** | Blue | +| **生成物** | 統合検証レポート | + +--- + +### gsd-ui-checker + +**役割:** UI-SPEC.md のデザインコントラクトを品質ディメンションに対して検証する。 + +| プロパティ | 値 | +|------------|-----| +| **スポーン元** | `/gsd-ui-phase`（検証ループ、最大2回の反復） | +| **並列数** | 単一インスタンス | +| **ツール** | read, bash, glob, grep | +| **モデル (balanced)** | Sonnet | +| **カラー** | `#22D3EE`（シアン） | +| **生成物** | BLOCK/FLAG/PASS 判定 | + +--- + +### gsd-verifier + +**役割:** ゴール逆算分析によりフェーズ目標の達成を検証する。 + +| プロパティ | 値 | +|------------|-----| +| **スポーン元** | `/gsd-execute-phase`（すべてのエグゼキューター完了後） | +| **並列数** | 単一インスタンス | +| **ツール** | read, write, bash, grep, glob | +| **モデル (balanced)** | Sonnet | +| **カラー** | Green | +| **生成物** | `{phase}-VERIFICATION.md` | + +**主な動作:** +- タスク完了だけでなく、フェーズ目標に対してコードベースを検証 +- 具体的なエビデンス付きの PASS/FAIL 判定 +- `/gsd-verify-work` で対処すべき問題をログに記録 + +--- + +### gsd-nyquist-auditor + +**役割:** テストを生成して Nyquist バリデーションのギャップを埋める。 + +| プロパティ | 値 | +|------------|-----| +| **スポーン元** | `/gsd-validate-phase` | +| **並列数** | 単一インスタンス | +| **ツール** | read, write, edit, bash, grep, glob | +| **モデル (balanced)** | Sonnet | +| **生成物** | テストファイル、更新された `VALIDATION.md` | + +**主な動作:** +- 実装コードは一切変更しない — テストファイルのみ +- ギャップごとに最大3回の試行 +- 実装のバグはユーザーへのエスカレーションとしてフラグを付与 + +--- + +### gsd-ui-auditor + +**役割:** 実装済みフロントエンドコードの事後的な6ピラービジュアル監査を行う。 + +| プロパティ | 値 | +|------------|-----| +| **スポーン元** | `/gsd-ui-review` | +| **並列数** | 単一インスタンス | +| **ツール** | read, write, bash, grep, glob | +| **モデル (balanced)** | Sonnet | +| **カラー** | `#F472B6`（ピンク） | +| **生成物** | スコア付きの `{phase}-UI-REVIEW.md` | + +**6つの監査ピラー（1〜4でスコアリング）:** +1. コピーライティング +2. ビジュアル +3. カラー +4. タイポグラフィ +5. スペーシング +6. エクスペリエンスデザイン + +--- + +### gsd-codebase-mapper + +**役割:** コードベースを探索し、構造化された分析ドキュメントを作成する。 + +| プロパティ | 値 | +|------------|-----| +| **スポーン元** | `/gsd-map-codebase` | +| **並列数** | 4インスタンス（tech, architecture, quality, concerns） | +| **ツール** | read, bash, grep, glob, write | +| **モデル (balanced)** | Haiku | +| **カラー** | Cyan | +| **生成物** | `.planning/codebase/*.md`（7ドキュメント） | + +**主な動作:** +- 読み取り専用の探索 + 構造化された出力 +- ドキュメントを直接ディスクに書き込み +- 推論不要 — ファイル内容からのパターン抽出 + +--- + +### gsd-debugger + +**役割:** 永続的な状態を持つ科学的手法でバグを調査する。 + +| プロパティ | 値 | +|------------|-----| +| **スポーン元** | `/gsd-debug`, `/gsd-verify-work`（失敗時） | +| **並列数** | 単一インスタンス（インタラクティブ） | +| **ツール** | read, write, edit, bash, grep, glob, websearch | +| **モデル (balanced)** | Sonnet | +| **カラー** | Orange | +| **生成物** | `.planning/debug/*.md`、ナレッジベースの更新 | + +**デバッグセッションのライフサイクル:** +`gathering` → `investigating` → `fixing` → `verifying` → `awaiting_human_verify` → `resolved` + +**主な動作:** +- 仮説、エビデンス、排除された理論を追跡 +- コンテキストリセット後も状態が永続化 +- 解決済みとマークする前に人間による検証を要求 +- 解決時に永続的なナレッジベースに追記 +- 新しいセッション開始時にナレッジベースを参照 + +--- + +### gsd-user-profiler + +**役割:** 8つの行動ディメンションにわたってセッションメッセージを分析し、スコア付きの開発者プロファイルを作成する。 + +| プロパティ | 値 | +|------------|-----| +| **スポーン元** | `/gsd-profile-user` | +| **並列数** | 単一インスタンス | +| **ツール** | read | +| **モデル (balanced)** | Sonnet | +| **カラー** | Magenta | +| **生成物** | `USER-PROFILE.md`、`/gsd-dev-preferences`、`AGENTS.md` プロファイルセクション | + +**行動ディメンション:** +コミュニケーションスタイル、意思決定パターン、デバッグアプローチ、UXの好み、ベンダー選択、フラストレーショントリガー、学習スタイル、説明の深度。 + +**主な動作:** +- 読み取り専用エージェント — 抽出されたセッションデータを分析し、ファイルは変更しない +- 信頼度レベルとエビデンス引用を含むスコア付きディメンションを生成 +- セッション履歴が利用できない場合はアンケートにフォールバック + +--- + +## エージェントツール権限サマリー + +| エージェント | read | write | edit | bash | grep | glob | websearch | webfetch | MCP | +|-------------|------|-------|------|------|------|------|-----------|----------|-----| +| project-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| phase-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| ui-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| assumptions-analyzer | ✓ | | | ✓ | ✓ | ✓ | | | | +| advisor-researcher | ✓ | | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| research-synthesizer | ✓ | ✓ | | ✓ | | | | | | +| planner | ✓ | ✓ | | ✓ | ✓ | ✓ | | ✓ | ✓ | +| roadmapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | | +| executor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | | +| plan-checker | ✓ | | | ✓ | ✓ | ✓ | | | | +| integration-checker | ✓ | | | ✓ | ✓ | ✓ | | | | +| ui-checker | ✓ | | | ✓ | ✓ | ✓ | | | | +| verifier | ✓ | ✓ | | ✓ | ✓ | ✓ | | | | +| nyquist-auditor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | | +| ui-auditor | ✓ | ✓ | | ✓ | ✓ | ✓ | | | | +| codebase-mapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | | +| debugger | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | +| user-profiler | ✓ | | | | | | | | | + +**最小権限の原則:** +- チェッカーは読み取り専用（write/edit なし） — 評価のみを行い、変更は行わない +- リサーチャーは Web アクセスを持つ — 最新のエコシステム情報が必要なため +- エグゼキューターは edit を持つ — コードを変更するが Web アクセスは不要 +- マッパーは write を持つ — 分析ドキュメントを作成するが edit は不要（コード変更なし） diff --git a/gsd-opencode/docs/ja-JP/ARCHITECTURE.md b/gsd-opencode/docs/ja-JP/ARCHITECTURE.md new file mode 100644 index 0000000..c7fc45c --- /dev/null +++ b/gsd-opencode/docs/ja-JP/ARCHITECTURE.md @@ -0,0 +1,527 @@ +# GSD アーキテクチャ + +> コントリビューターおよび上級ユーザー向けのシステムアーキテクチャ文書です。ユーザー向けドキュメントは[機能リファレンス](FEATURES.md)または[ユーザーガイド](USER-GUIDE.md)をご覧ください。 + +--- + +## 目次 + +- [システム概要](#システム概要) +- [設計原則](#設計原則) +- [コンポーネントアーキテクチャ](#コンポーネントアーキテクチャ) +- [エージェントモデル](#エージェントモデル) +- [データフロー](#データフロー) +- [ファイルシステムレイアウト](#ファイルシステムレイアウト) +- [インストーラーアーキテクチャ](#インストーラーアーキテクチャ) +- [フックシステム](#フックシステム) +- [CLIツールレイヤー](#cliツールレイヤー) +- [ランタイム抽象化](#ランタイム抽象化) + +--- + +## システム概要 + +GSDは、ユーザーとAIコーディングエージェント（OpenCode、Gemini CLI、OpenCode、Codex、Copilot、Antigravity）の間に位置する**メタプロンプティングフレームワーク**です。以下の機能を提供します： + +1. **コンテキストエンジニアリング** — タスクごとにAIが必要とするすべてを提供する構造化アーティファクト +2. **マルチエージェントオーケストレーション** — 専門エージェントをフレッシュなコンテキストウィンドウで起動する軽量オーケストレーター +3. **仕様駆動開発** — 要件 → 調査 → 計画 → 実行 → 検証のパイプライン +4. **状態管理** — セッションやコンテキストリセットをまたいだ永続的なプロジェクトメモリ + +``` +┌──────────────────────────────────────────────────────┐ +│ USER │ +│ /gsd-command [args] │ +└─────────────────────┬────────────────────────────────┘ + │ +┌─────────────────────▼────────────────────────────────┐ +│ COMMAND LAYER │ +│ commands/gsd/*.md — Prompt-based command files │ +│ (OpenCode custom commands / Codex skills) │ +└─────────────────────┬────────────────────────────────┘ + │ +┌─────────────────────▼────────────────────────────────┐ +│ WORKFLOW LAYER │ +│ get-shit-done/workflows/*.md — Orchestration logic │ +│ (Reads references, spawns agents, manages state) │ +└──────┬──────────────┬─────────────────┬──────────────┘ + │ │ │ +┌──────▼──────┐ ┌─────▼─────┐ ┌────────▼───────┐ +│ AGENT │ │ AGENT │ │ AGENT │ +│ (fresh │ │ (fresh │ │ (fresh │ +│ context) │ │ context)│ │ context) │ +└──────┬──────┘ └─────┬─────┘ └────────┬───────┘ + │ │ │ +┌──────▼──────────────▼─────────────────▼──────────────┐ +│ CLI TOOLS LAYER │ +│ get-shit-done/bin/gsd-tools.cjs │ +│ (State, config, phase, roadmap, verify, templates) │ +└──────────────────────┬───────────────────────────────┘ + │ +┌──────────────────────▼───────────────────────────────┐ +│ FILE SYSTEM (.planning/) │ +│ PROJECT.md | REQUIREMENTS.md | ROADMAP.md │ +│ STATE.md | config.json | phases/ | research/ │ +└──────────────────────────────────────────────────────┘ +``` + +--- + +## 設計原則 + +### 1. エージェントごとにフレッシュなコンテキスト + +オーケストレーターが起動するすべてのエージェントは、クリーンなコンテキストウィンドウ（最大200Kトークン）を取得します。これにより、AIがコンテキストウィンドウに蓄積された会話で埋め尽くされることによる品質低下（コンテキストの劣化）が排除されます。 + +### 2. 軽量オーケストレーター + +ワークフローファイル（`get-shit-done/workflows/*.md`）は重い処理を行いません。以下の役割に徹します： +- `gsd-tools.cjs init ` でコンテキストを読み込む +- 焦点を絞ったプロンプトで専門エージェントを起動する +- 結果を収集し、次のステップにルーティングする +- ステップ間で状態を更新する + +### 3. ファイルベースの状態管理 + +すべての状態は `.planning/` 内に人間が読めるMarkdownとJSONとして保存されます。データベースもサーバーも外部依存もありません。これにより： +- コンテキストリセット（`/new`）後も状態が維持される +- 人間とエージェントの両方が状態を確認できる +- チームでの可視性のためにgitにコミットできる + +### 4. 未設定 = 有効 + +ワークフローの機能フラグは **未設定 = 有効** のパターンに従います。`config.json` にキーが存在しない場合、デフォルトで `true` になります。ユーザーは機能を明示的に無効化します。デフォルトを有効化する操作は不要です。 + +### 5. 多層防御 + +複数のレイヤーで一般的な障害モードを防止します： +- 実行前に計画が検証される（plan-checkerエージェント） +- 実行時にタスクごとにアトミックなコミットが生成される +- 実行後の検証でフェーズ目標との整合性を確認する +- UATが最終ゲートとして人間による検証を提供する + +--- + +## コンポーネントアーキテクチャ + +### コマンド（`commands/gsd/*.md`） + +ユーザー向けのエントリーポイントです。各ファイルにはYAMLフロントマター（name、description、allowed-tools）とワークフローをブートストラップするプロンプト本文が含まれています。コマンドは以下の形式でインストールされます： +- **OpenCode:** カスタムスラッシュコマンド（`/gsd-command-name`） +- **OpenCode:** スラッシュコマンド（`/gsd-command-name`） +- **Codex:** スキル（`$gsd-command-name`） +- **Copilot:** スラッシュコマンド（`/gsd-command-name`） +- **Antigravity:** スキル + +**コマンド総数:** 44 + +### ワークフロー（`get-shit-done/workflows/*.md`） + +コマンドが参照するオーケストレーションロジックです。以下を含むステップバイステップのプロセスが記述されています： +- `gsd-tools.cjs init` によるコンテキスト読み込み +- モデル解決を伴うエージェント起動の指示 +- ゲート/チェックポイントの定義 +- 状態更新パターン +- エラーハンドリングとリカバリー + +**ワークフロー総数:** 46 + +### エージェント（`agents/*.md`） + +フロントマターで以下を指定する専門エージェント定義： +- `name` — エージェント識別子 +- `description` — 役割と目的 +- `tools` — 許可されたツールアクセス（read、write、edit、bash、grep、glob、websearchなど） +- `color` — 視覚的な区別のためのターミナル出力色 + +**エージェント総数:** 16 + +### リファレンス（`get-shit-done/references/*.md`） + +ワークフローとエージェントが `@-reference` で参照する共有知識ドキュメント： +- `checkpoints.md` — チェックポイントタイプの定義とインタラクションパターン +- `model-profiles.md` — エージェントごとのモデルティア割り当て +- `verification-patterns.md` — 各種アーティファクトの検証方法 +- `planning-config.md` — 設定スキーマの全体像と動作 +- `git-integration.md` — gitコミット、ブランチ、履歴のパターン +- `questioning.md` — プロジェクト初期化のためのドリーム抽出フィロソフィー +- `tdd.md` — テスト駆動開発の統合パターン +- `ui-brand.md` — 視覚的な出力フォーマットパターン + +### テンプレート（`get-shit-done/templates/`） + +すべてのプランニングアーティファクト用のMarkdownテンプレートです。`gsd-tools.cjs template fill` および `scaffold` コマンドにより、事前構造化されたファイルを作成するために使用されます： +- `project.md`、`requirements.md`、`roadmap.md`、`state.md` — コアプロジェクトファイル +- `phase-prompt.md` — フェーズ実行プロンプトテンプレート +- `summary.md`（+ `summary-minimal.md`、`summary-standard.md`、`summary-complex.md`）— 粒度対応のサマリーテンプレート +- `DEBUG.md` — デバッグセッション追跡テンプレート +- `UI-SPEC.md`、`UAT.md`、`VALIDATION.md` — 専門検証テンプレート +- `discussion-log.md` — ディスカッション監査証跡テンプレート +- `codebase/` — ブラウンフィールドマッピングテンプレート（スタック、アーキテクチャ、規約、懸念事項、構造、テスト、統合） +- `research-project/` — リサーチ出力テンプレート（SUMMARY、STACK、FEATURES、ARCHITECTURE、PITFALLS） + +### フック（`hooks/`） + +ホストAIエージェントと統合するランタイムフック： + +| フック | イベント | 目的 | +|------|-------|---------| +| `gsd-statusline.js` | `statusLine` | モデル、タスク、ディレクトリ、コンテキスト使用量バーを表示 | +| `gsd-context-monitor.js` | `PostToolUse` / `AfterTool` | コンテキスト残量35%/25%でエージェント向け警告を注入 | +| `gsd-check-update.js` | `SessionStart` | GSDの新バージョンをバックグラウンドで確認 | +| `gsd-prompt-guard.js` | `PreToolUse` | `.planning/` への書き込みにプロンプトインジェクションパターンがないかスキャン（アドバイザリー） | +| `gsd-workflow-guard.js` | `PreToolUse` | GSDワークフローコンテキスト外でのファイル編集を検出（アドバイザリー、`hooks.workflow_guard` によるオプトイン） | + +### CLIツール（`get-shit-done/bin/`） + +17のドメインモジュールを持つNode.js CLIユーティリティ（`gsd-tools.cjs`）： + +| モジュール | 責務 | +|--------|---------------| +| `core.cjs` | エラーハンドリング、出力フォーマット、共有ユーティリティ | +| `state.cjs` | STATE.md の解析、更新、進行、メトリクス | +| `phase.cjs` | フェーズディレクトリ操作、小数番号付け、プランインデックス | +| `roadmap.cjs` | ROADMAP.md の解析、フェーズ抽出、プラン進捗 | +| `config.cjs` | config.json の読み書き、セクション初期化 | +| `verify.cjs` | プラン構造、フェーズ完了度、リファレンス、コミット検証 | +| `template.cjs` | テンプレート選択と変数置換による穴埋め | +| `frontmatter.cjs` | YAMLフロントマターのCRUD操作 | +| `init.cjs` | ワークフロータイプごとの複合コンテキスト読み込み | +| `milestone.cjs` | マイルストーンのアーカイブ、要件マーキング | +| `commands.cjs` | その他コマンド（slug、タイムスタンプ、todos、スキャフォールディング、統計） | +| `model-profiles.cjs` | モデルプロファイル解決テーブル | +| `security.cjs` | パストラバーサル防止、プロンプトインジェクション検出、安全なJSON解析、シェル引数バリデーション | +| `uat.cjs` | UATファイル解析、検証デット追跡、audit-uatサポート | + +--- + +## エージェントモデル + +### オーケストレーター → エージェントパターン + +``` +Orchestrator (workflow .md) + │ + ├── Load context: gsd-tools.cjs init + │ Returns JSON with: project info, config, state, phase details + │ + ├── Resolve model: gsd-tools.cjs resolve-model + │ Returns: opus | sonnet | haiku | inherit + │ + ├── Spawn Agent (task/SubAgent call) + │ ├── Agent prompt (agents/*.md) + │ ├── Context payload (init JSON) + │ ├── Model assignment + │ └── Tool permissions + │ + ├── Collect result + │ + └── Update state: gsd-tools.cjs state update/patch/advance-plan +``` + +### エージェント起動カテゴリ + +| カテゴリ | エージェント | 並列実行 | +|----------|--------|-------------| +| **リサーチャー** | gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher, gsd-advisor-researcher | 4並列（stack、features、architecture、pitfalls）; advisorはdiscuss-phase中に起動 | +| **シンセサイザー** | gsd-research-synthesizer | 逐次（リサーチャー完了後） | +| **プランナー** | gsd-planner, gsd-roadmapper | 逐次 | +| **チェッカー** | gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor | 逐次（検証ループ、最大3回反復） | +| **エグゼキューター** | gsd-executor | ウェーブ内は並列、ウェーブ間は逐次 | +| **ベリファイアー** | gsd-verifier | 逐次（全エグゼキューター完了後） | +| **マッパー** | gsd-codebase-mapper | 4並列（tech、arch、quality、concerns） | +| **デバッガー** | gsd-debugger | 逐次（インタラクティブ） | +| **オーディター** | gsd-ui-auditor | 逐次 | + +### ウェーブ実行モデル + +`execute-phase` では、プランが依存関係に基づいてウェーブにグループ化されます： + +``` +Wave Analysis: + Plan 01 (no deps) ─┐ + Plan 02 (no deps) ─┤── Wave 1 (parallel) + Plan 03 (depends: 01) ─┤── Wave 2 (waits for Wave 1) + Plan 04 (depends: 02) ─┘ + Plan 05 (depends: 03,04) ── Wave 3 (waits for Wave 2) +``` + +各エグゼキューターには以下が与えられます： +- フレッシュな200Kコンテキストウィンドウ +- 実行対象の特定のPLAN.md +- プロジェクトコンテキスト（PROJECT.md、STATE.md） +- フェーズコンテキスト（CONTEXT.md、利用可能な場合はRESEARCH.md） + +#### 並列コミットの安全性 + +同一ウェーブ内で複数のエグゼキューターが実行される場合、2つの仕組みで競合を防止します： + +1. **`--no-verify` コミット** — 並列エージェントはpre-commitフックをスキップします（ビルドロックの競合を引き起こす可能性があるため。例：Rustプロジェクトでのcargo lockファイルの競合）。オーケストレーターは各ウェーブ完了後に `git hook run pre-commit` を1回実行します。 + +2. **STATE.md ファイルロック** — すべての `writeStateMd()` 呼び出しはロックファイルベースの相互排他（`STATE.md.lock`、`O_EXCL` によるアトミック作成）を使用します。これにより、2つのエージェントがSTATE.mdを読み取り、異なるフィールドを変更し、最後の書き込みが他方の変更を上書きする読み取り-変更-書き込みの競合状態を防止します。古いロックの検出（10秒タイムアウト）とジッター付きのスピンウェイトを含みます。 + +--- + +## データフロー + +### 新規プロジェクトフロー + +``` +User input (idea description) + │ + ▼ +Questions (questioning.md philosophy) + │ + ▼ +4x Project Researchers (parallel) + ├── Stack → STACK.md + ├── Features → FEATURES.md + ├── Architecture → ARCHITECTURE.md + └── Pitfalls → PITFALLS.md + │ + ▼ +Research Synthesizer → SUMMARY.md + │ + ▼ +Requirements extraction → REQUIREMENTS.md + │ + ▼ +Roadmapper → ROADMAP.md + │ + ▼ +User approval → STATE.md initialized +``` + +### フェーズ実行フロー + +``` +discuss-phase → CONTEXT.md (user preferences) + │ + ▼ +ui-phase → UI-SPEC.md (design contract, optional) + │ + ▼ +plan-phase + ├── Phase Researcher → RESEARCH.md + ├── Planner → PLAN.md files + └── Plan Checker → Verify loop (max 3x) + │ + ▼ +execute-phase + ├── Wave analysis (dependency grouping) + ├── Executor per plan → code + atomic commits + ├── SUMMARY.md per plan + └── Verifier → VERIFICATION.md + │ + ▼ +verify-work → UAT.md (user acceptance testing) + │ + ▼ +ui-review → UI-REVIEW.md (visual audit, optional) +``` + +### コンテキスト伝播 + +各ワークフローステージは後続のステージに供給されるアーティファクトを生成します： + +``` +PROJECT.md ────────────────────────────────────────────► All agents +REQUIREMENTS.md ───────────────────────────────────────► Planner, Verifier, Auditor +ROADMAP.md ────────────────────────────────────────────► Orchestrators +STATE.md ──────────────────────────────────────────────► All agents (decisions, blockers) +CONTEXT.md (per phase) ────────────────────────────────► Researcher, Planner, Executor +RESEARCH.md (per phase) ───────────────────────────────► Planner, Plan Checker +PLAN.md (per plan) ────────────────────────────────────► Executor, Plan Checker +SUMMARY.md (per plan) ─────────────────────────────────► Verifier, State tracking +UI-SPEC.md (per phase) ────────────────────────────────► Executor, UI Auditor +``` + +--- + +## ファイルシステムレイアウト + +### インストールファイル + +``` +$HOME/.config/opencode/ # OpenCode (global install) +├── commands/gsd/*.md # 37 slash commands +├── get-shit-done/ +│ ├── bin/gsd-tools.cjs # CLI utility +│ ├── bin/lib/*.cjs # 15 domain modules +│ ├── workflows/*.md # 42 workflow definitions +│ ├── references/*.md # 13 shared reference docs +│ └── templates/ # Planning artifact templates +├── agents/*.md # 15 agent definitions +├── hooks/ +│ ├── gsd-statusline.js # Statusline hook +│ ├── gsd-context-monitor.js # Context warning hook +│ └── gsd-check-update.js # Update check hook +├── settings.json # Hook registrations +└── VERSION # Installed version number +``` + +他のランタイムでの同等パス： +- **OpenCode:** `~/.config/opencode/` または `~/.opencode/` +- **Gemini CLI:** `~/.gemini/` +- **Codex:** `~/.codex/`（コマンドの代わりにスキルを使用） +- **Copilot:** `~/.github/` +- **Antigravity:** `~/.gemini/antigravity/`（グローバル）または `./.agent/`（ローカル） + +### プロジェクトファイル（`.planning/`） + +``` +.planning/ +├── PROJECT.md # プロジェクトビジョン、制約、決定事項、発展ルール +├── REQUIREMENTS.md # スコープ付き要件（v1/v2/スコープ外） +├── ROADMAP.md # ステータス追跡付きフェーズ分解 +├── STATE.md # 生きたメモリ：位置、決定事項、ブロッカー、メトリクス +├── config.json # ワークフロー設定 +├── MILESTONES.md # 完了済みマイルストーンのアーカイブ +├── research/ # /gsd-new-project によるドメインリサーチ +│ ├── SUMMARY.md +│ ├── STACK.md +│ ├── FEATURES.md +│ ├── ARCHITECTURE.md +│ └── PITFALLS.md +├── codebase/ # ブラウンフィールドマッピング（/gsd-map-codebase から） +│ ├── STACK.md +│ ├── ARCHITECTURE.md +│ ├── CONVENTIONS.md +│ ├── CONCERNS.md +│ ├── STRUCTURE.md +│ ├── TESTING.md +│ └── INTEGRATIONS.md +├── phases/ +│ └── XX-phase-name/ +│ ├── XX-CONTEXT.md # ユーザー設定（discuss-phase から） +│ ├── XX-RESEARCH.md # エコシステムリサーチ（plan-phase から） +│ ├── XX-YY-PLAN.md # 実行プラン +│ ├── XX-YY-SUMMARY.md # 実行結果 +│ ├── XX-VERIFICATION.md # 実行後の検証 +│ ├── XX-VALIDATION.md # ナイキストテストカバレッジマッピング +│ ├── XX-UI-SPEC.md # UIデザインコントラクト（ui-phase から） +│ ├── XX-UI-REVIEW.md # ビジュアル監査スコア（ui-review から） +│ └── XX-UAT.md # ユーザー受け入れテスト結果 +├── quick/ # クイックタスク追跡 +│ └── YYMMDD-xxx-slug/ +│ ├── PLAN.md +│ └── SUMMARY.md +├── todos/ +│ ├── pending/ # キャプチャされたアイデア +│ └── done/ # 完了済みtodo +├── threads/ # 永続コンテキストスレッド（/gsd-thread から） +├── seeds/ # 将来に向けたアイデア（/gsd-plant-seed から） +├── debug/ # アクティブなデバッグセッション +│ ├── *.md # アクティブセッション +│ ├── resolved/ # アーカイブ済みセッション +│ └── knowledge-base.md # 永続的なデバッグ知見 +├── ui-reviews/ # /gsd-ui-review からのスクリーンショット（gitignore対象） +└── continue-here.md # コンテキスト引き継ぎ（pause-work から） +``` + +--- + +## インストーラーアーキテクチャ + +インストーラー（`bin/install.js`、約3,000行）は以下を処理します： + +1. **ランタイム検出** — インタラクティブプロンプトまたはCLIフラグ（`--OpenCode`、`--opencode`、`--gemini`、`--codex`、`--copilot`、`--antigravity`、`--all`） +2. **インストール先の選択** — グローバル（`--global`）またはローカル（`--local`） +3. **ファイルデプロイ** — コマンド、ワークフロー、リファレンス、テンプレート、エージェント、フックをコピー +4. **ランタイム適応** — ランタイムごとにファイル内容を変換： + - OpenCode: そのまま使用 + - OpenCode: エージェントフロントマターを `name:`、`model: inherit`、`mode: subagent` に変換 + - Codex: コマンドからTOML設定 + スキルを生成 + - Copilot: ツール名をマッピング（read→read、bash→executeなど） + - Gemini: フックイベント名を調整（`PostToolUse` の代わりに `AfterTool`） + - Antigravity: Googleモデル同等品によるスキルファースト +5. **パス正規化** — `$HOME/.config/opencode/` パスをランタイム固有のパスに置換 +6. **設定統合** — ランタイムの `settings.json` にフックを登録 +7. **パッチバックアップ** — v1.17以降、ローカルで変更されたファイルを `/gsd-reapply-patches` 用に `gsd-local-patches/` へバックアップ +8. **マニフェスト追跡** — クリーンアンインストールのために `gsd-file-manifest.json` を書き込み +9. **アンインストールモード** — `--uninstall` ですべてのGSDファイル、フック、設定を削除 + +### プラットフォーム対応 + +- **Windows:** 子プロセスでの `windowsHide`、保護ディレクトリへのEPERM/EACCES対策、パスセパレーターの正規化 +- **WSL:** WindowsのNode.jsがWSL上で実行されていることを検出し、パスの不一致について警告 +- **Docker/CI:** カスタム設定ディレクトリの場所に `CLAUDE_CONFIG_DIR` 環境変数をサポート + +--- + +## フックシステム + +### アーキテクチャ + +``` +Runtime Engine (OpenCode / Gemini CLI) + │ + ├── statusLine event ──► gsd-statusline.js + │ Reads: stdin (session JSON) + │ Writes: stdout (formatted status), /tmp/OpenCode-ctx-{session}.json (bridge) + │ + ├── PostToolUse/AfterTool event ──► gsd-context-monitor.js + │ Reads: stdin (tool event JSON), /tmp/OpenCode-ctx-{session}.json (bridge) + │ Writes: stdout (hookSpecificOutput with additionalContext warning) + │ + └── SessionStart event ──► gsd-check-update.js + Reads: VERSION file + Writes: $HOME/.config/opencode/cache/gsd-update-check.json (spawns background process) +``` + +### コンテキストモニターの閾値 + +| コンテキスト残量 | レベル | エージェントの動作 | +|-------------------|-------|----------------| +| > 35% | Normal | 警告なし | +| ≤ 35% | WARNING | 「新しい複雑な作業の開始を避けてください」 | +| ≤ 25% | CRITICAL | 「コンテキストがほぼ枯渇、ユーザーに通知してください」 | + +デバウンス：繰り返し警告の間隔は5回のツール使用。重大度のエスカレーション（WARNING→CRITICAL）はデバウンスをバイパスします。 + +### 安全性の特性 + +- すべてのフックはtry/catchでラップされ、エラー時はサイレントに終了 +- stdin タイムアウトガード（3秒）でパイプの問題によるハングを防止 +- 古いメトリクス（60秒超）は無視される +- ブリッジファイルの欠落は適切に処理される（サブエージェント、新規セッション） +- コンテキストモニターはアドバイザリーのみ — ユーザーの設定を上書きする命令的なコマンドは発行しない + +### セキュリティフック（v1.27） + +**Prompt Guard**（`gsd-prompt-guard.js`）： +- `.planning/` ファイルへのwrite/edit時にトリガー +- プロンプトインジェクションパターン（ロールオーバーライド、指示バイパス、systemタグインジェクション）をスキャン +- アドバイザリーのみ — 検出をログに記録するが、ブロックはしない +- フックの独立性のため、パターンはインライン化（`security.cjs` のサブセット） + +**Workflow Guard**（`gsd-workflow-guard.js`）： +- `.planning/` 以外のファイルへのwrite/edit時にトリガー +- GSDワークフローコンテキスト外での編集を検出（アクティブな `/gsd-` コマンドやtaskサブエージェントがない場合） +- 状態追跡される変更には `/gsd-quick` や `/gsd-fast` の使用をアドバイス +- `hooks.workflow_guard: true` によるオプトイン（デフォルト: false） + +--- + +## ランタイム抽象化 + +GSDは統一されたコマンド/ワークフローアーキテクチャを通じて6つのAIコーディングランタイムをサポートしています： + +| ランタイム | コマンド形式 | エージェントシステム | 設定場所 | +|---------|---------------|--------------|-----------------| +| OpenCode | `/gsd-command` | task起動 | `$HOME/.config/opencode/` | +| OpenCode | `/gsd-command` | サブエージェントモード | `~/.config/opencode/` | +| Gemini CLI | `/gsd-command` | task起動 | `~/.gemini/` | +| Codex | `$gsd-command` | スキル | `~/.codex/` | +| Copilot | `/gsd-command` | エージェント委譲 | `~/.github/` | +| Antigravity | スキル | スキル | `~/.gemini/antigravity/` | + +### 抽象化ポイント + +1. **ツール名マッピング** — 各ランタイムは独自のツール名を持つ（例：OpenCodeのbash → Copilotのexecute） +2. **フックイベント名** — OpenCodeは `PostToolUse`、Geminiは `AfterTool` を使用 +3. **エージェントフロントマター** — 各ランタイムは独自のエージェント定義形式を持つ +4. **パス規約** — 各ランタイムは異なるディレクトリに設定を保存 +5. **モデル参照** — `inherit` プロファイルにより、GSDはランタイムのモデル選択に委譲 + +インストーラーはインストール時にすべての変換を処理します。ワークフローとエージェントはOpenCodeのネイティブ形式で記述され、デプロイ時に変換されます。 diff --git a/gsd-opencode/docs/ja-JP/CLI-TOOLS.md b/gsd-opencode/docs/ja-JP/CLI-TOOLS.md new file mode 100644 index 0000000..926b025 --- /dev/null +++ b/gsd-opencode/docs/ja-JP/CLI-TOOLS.md @@ -0,0 +1,367 @@ +# GSD CLI ツールリファレンス + +> `gsd-tools.cjs` のプログラマティック API リファレンスです。ワークフローやエージェントが内部的に使用します。ユーザー向けコマンドについては、[コマンドリファレンス](COMMANDS.md) を参照してください。 + +--- + +## 概要 + +`gsd-tools.cjs` は、GSD の約50個のコマンド、ワークフロー、エージェントファイル全体で繰り返し使われるインライン bash パターンを置き換える Node.js CLI ユーティリティです。設定の解析、モデル解決、フェーズ検索、git コミット、サマリー検証、状態管理、テンプレート操作を一元化しています。 + +**配置場所:** `get-shit-done/bin/gsd-tools.cjs` +**モジュール:** `get-shit-done/bin/lib/` 内の15個のドメインモジュール + +**使い方:** +```bash +node gsd-tools.cjs [args] [--raw] [--cwd ] +``` + +**グローバルフラグ:** +| フラグ | 説明 | +|--------|------| +| `--raw` | 機械可読な出力（JSON またはプレーンテキスト、フォーマットなし） | +| `--cwd ` | 作業ディレクトリの上書き（サンドボックス化されたサブエージェント向け） | + +--- + +## State コマンド + +`.planning/STATE.md` を管理します — プロジェクトの生きた記憶です。 + +```bash +# プロジェクトの全設定 + 状態を JSON として読み込む +node gsd-tools.cjs state load + +# STATE.md のフロントマターを JSON として出力 +node gsd-tools.cjs state json + +# 単一フィールドを更新 +node gsd-tools.cjs state update + +# STATE.md の内容または特定セクションを取得 +node gsd-tools.cjs state get [section] + +# 複数フィールドの一括更新 +node gsd-tools.cjs state patch --field1 val1 --field2 val2 + +# プランカウンターをインクリメント +node gsd-tools.cjs state advance-plan + +# 実行メトリクスを記録 +node gsd-tools.cjs state record-metric --phase N --plan M --duration Xmin [--tasks N] [--files N] + +# プログレスバーを再計算 +node gsd-tools.cjs state update-progress + +# 決定事項を追加 +node gsd-tools.cjs state add-decision --summary "..." [--phase N] [--rationale "..."] +# ファイルから追加する場合: +node gsd-tools.cjs state add-decision --summary-file path [--rationale-file path] + +# ブロッカーの追加・解決 +node gsd-tools.cjs state add-blocker --text "..." +node gsd-tools.cjs state resolve-blocker --text "..." + +# セッション継続性を記録 +node gsd-tools.cjs state record-session --stopped-at "..." [--resume-file path] +``` + +### State スナップショット + +STATE.md 全体の構造化パース: + +```bash +node gsd-tools.cjs state-snapshot +``` + +現在位置、フェーズ、プラン、ステータス、決定事項、ブロッカー、メトリクス、最終アクティビティを含む JSON を返します。 + +--- + +## Phase コマンド + +フェーズを管理します — ディレクトリ、番号付け、ロードマップとの同期。 + +```bash +# 番号でフェーズディレクトリを検索 +node gsd-tools.cjs find-phase + +# 挿入用の次の小数フェーズ番号を計算 +node gsd-tools.cjs phase next-decimal + +# ロードマップに新しいフェーズを追加 + ディレクトリを作成 +node gsd-tools.cjs phase add + +# 既存フェーズの後に小数フェーズを挿入 +node gsd-tools.cjs phase insert + +# フェーズを削除し、後続を振り直し +node gsd-tools.cjs phase remove [--force] + +# フェーズを完了としてマークし、状態 + ロードマップを更新 +node gsd-tools.cjs phase complete + +# ウェーブとステータス付きでプランをインデックス化 +node gsd-tools.cjs phase-plan-index + +# フィルタリング付きでフェーズを一覧表示 +node gsd-tools.cjs phases list [--type planned|executed|all] [--phase N] [--include-archived] +``` + +--- + +## Roadmap コマンド + +`ROADMAP.md` の解析と更新。 + +```bash +# ROADMAP.md からフェーズセクションを抽出 +node gsd-tools.cjs roadmap get-phase + +# ディスク状態を含む完全なロードマップ解析 +node gsd-tools.cjs roadmap analyze + +# ディスクからプログレステーブル行を更新 +node gsd-tools.cjs roadmap update-plan-progress +``` + +--- + +## Config コマンド + +`.planning/config.json` の読み書き。 + +```bash +# デフォルト値で config.json を初期化 +node gsd-tools.cjs config-ensure-section + +# 設定値をセット（ドット記法） +node gsd-tools.cjs config-set + +# 設定値を取得 +node gsd-tools.cjs config-get + +# モデルプロファイルを設定 +node gsd-tools.cjs config-set-model-profile +``` + +--- + +## モデル解決 + +```bash +# 現在のプロファイルに基づいてエージェント用モデルを取得 +node gsd-tools.cjs resolve-model +# 戻り値: opus | sonnet | haiku | inherit +``` + +エージェント名: `gsd-planner`, `gsd-executor`, `gsd-phase-researcher`, `gsd-project-researcher`, `gsd-research-synthesizer`, `gsd-verifier`, `gsd-plan-checker`, `gsd-integration-checker`, `gsd-roadmapper`, `gsd-debugger`, `gsd-codebase-mapper`, `gsd-nyquist-auditor` + +--- + +## Verification コマンド + +プラン、フェーズ、参照、コミットを検証します。 + +```bash +# SUMMARY.md ファイルを検証 +node gsd-tools.cjs verify-summary [--check-count N] + +# PLAN.md の構造 + タスクをチェック +node gsd-tools.cjs verify plan-structure + +# 全プランにサマリーがあるか確認 +node gsd-tools.cjs verify phase-completeness + +# @参照 + パスが解決可能か確認 +node gsd-tools.cjs verify references + +# コミットハッシュの一括検証 +node gsd-tools.cjs verify commits [hash2] ... + +# must_haves.artifacts をチェック +node gsd-tools.cjs verify artifacts + +# must_haves.key_links をチェック +node gsd-tools.cjs verify key-links +``` + +--- + +## Validation コマンド + +プロジェクトの整合性をチェックします。 + +```bash +# フェーズ番号、ディスク/ロードマップの同期を確認 +node gsd-tools.cjs validate consistency + +# .planning/ の整合性チェック、任意で修復 +node gsd-tools.cjs validate health [--repair] +``` + +--- + +## Template コマンド + +テンプレートの選択と穴埋め。 + +```bash +# 粒度に基づいてサマリーテンプレートを選択 +node gsd-tools.cjs template select + +# 変数でテンプレートを穴埋め +node gsd-tools.cjs template fill --phase N [--plan M] [--name "..."] [--type execute|tdd] [--wave N] [--fields '{json}'] +``` + +`fill` のテンプレートタイプ: `summary`, `plan`, `verification` + +--- + +## Frontmatter コマンド + +任意の Markdown ファイルに対する YAML フロントマターの CRUD 操作。 + +```bash +# フロントマターを JSON として抽出 +node gsd-tools.cjs frontmatter get [--field key] + +# 単一フィールドを更新 +node gsd-tools.cjs frontmatter set --field key --value jsonVal + +# JSON をフロントマターにマージ +node gsd-tools.cjs frontmatter merge --data '{json}' + +# 必須フィールドを検証 +node gsd-tools.cjs frontmatter validate --schema plan|summary|verification +``` + +--- + +## Scaffold コマンド + +事前構造化されたファイルとディレクトリを作成します。 + +```bash +# CONTEXT.md テンプレートを作成 +node gsd-tools.cjs scaffold context --phase N + +# UAT.md テンプレートを作成 +node gsd-tools.cjs scaffold uat --phase N + +# VERIFICATION.md テンプレートを作成 +node gsd-tools.cjs scaffold verification --phase N + +# フェーズディレクトリを作成 +node gsd-tools.cjs scaffold phase-dir --phase N --name "phase name" +``` + +--- + +## Init コマンド（複合コンテキスト読み込み） + +特定のワークフローに必要なすべてのコンテキストを一度に読み込みます。プロジェクト情報、設定、状態、ワークフロー固有のデータを含む JSON を返します。 + +```bash +node gsd-tools.cjs init execute-phase +node gsd-tools.cjs init plan-phase +node gsd-tools.cjs init new-project +node gsd-tools.cjs init new-milestone +node gsd-tools.cjs init quick +node gsd-tools.cjs init resume +node gsd-tools.cjs init verify-work +node gsd-tools.cjs init phase-op +node gsd-tools.cjs init todos [area] +node gsd-tools.cjs init milestone-op +node gsd-tools.cjs init map-codebase +node gsd-tools.cjs init progress +``` + +**大容量ペイロードの処理:** 出力が約50KBを超える場合、CLI は一時ファイルに書き出し、`@file:/tmp/gsd-init-XXXXX.json` を返します。ワークフローは `@file:` プレフィックスを確認し、ディスクから読み込みます: + +```bash +INIT=$(node gsd-tools.cjs init execute-phase "1") +if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +``` + +--- + +## Milestone コマンド + +```bash +# マイルストーンをアーカイブ +node gsd-tools.cjs milestone complete [--name ] [--archive-phases] + +# 要件を完了としてマーク +node gsd-tools.cjs requirements mark-complete +# 受け付ける形式: REQ-01,REQ-02 または REQ-01 REQ-02 または [REQ-01, REQ-02] +``` + +--- + +## ユーティリティコマンド + +```bash +# テキストを URL セーフなスラッグに変換 +node gsd-tools.cjs generate-slug "Some Text Here" +# → some-text-here + +# タイムスタンプを取得 +node gsd-tools.cjs current-timestamp [full|date|filename] + +# 保留中の TODO をカウントして一覧表示 +node gsd-tools.cjs list-todos [area] + +# ファイル/ディレクトリの存在確認 +node gsd-tools.cjs verify-path-exists + +# 全 SUMMARY.md データを集約 +node gsd-tools.cjs history-digest + +# SUMMARY.md から構造化データを抽出 +node gsd-tools.cjs summary-extract [--fields field1,field2] + +# プロジェクト統計 +node gsd-tools.cjs stats [json|table] + +# 進捗表示 +node gsd-tools.cjs progress [json|table|bar] + +# TODO を完了にする +node gsd-tools.cjs todo complete + +# UAT 監査 — 全フェーズの未解決項目をスキャン +node gsd-tools.cjs audit-uat + +# 設定チェック付き git コミット +node gsd-tools.cjs commit [--files f1 f2] [--amend] [--no-verify] +``` + +> **`--no-verify`**: プリコミットフックをスキップします。ウェーブベース実行時に並列エグゼキューターエージェントが使用し、ビルドロックの競合（例: Rust プロジェクトでの cargo ロック競合）を回避します。オーケストレーターは各ウェーブ完了後にフックを一度実行します。順次実行時には `--no-verify` を使用せず、フックを通常通り実行してください。 + +```bash +# Web 検索（Brave API キーが必要） +node gsd-tools.cjs websearch [--limit N] [--freshness day|week|month] +``` + +--- + +## モジュールアーキテクチャ + +| モジュール | ファイル | エクスポート | +|------------|----------|--------------| +| Core | `lib/core.cjs` | `error()`, `output()`, `parseArgs()`, 共通ユーティリティ | +| State | `lib/state.cjs` | すべての `state` サブコマンド、`state-snapshot` | +| Phase | `lib/phase.cjs` | フェーズ CRUD、`find-phase`、`phase-plan-index`、`phases list` | +| Roadmap | `lib/roadmap.cjs` | ロードマップ解析、フェーズ抽出、進捗更新 | +| Config | `lib/config.cjs` | 設定の読み書き、セクション初期化 | +| Verify | `lib/verify.cjs` | すべての検証・バリデーションコマンド | +| Template | `lib/template.cjs` | テンプレート選択と変数の穴埋め | +| Frontmatter | `lib/frontmatter.cjs` | YAML フロントマター CRUD | +| Init | `lib/init.cjs` | 全ワークフロー向け複合コンテキスト読み込み | +| Milestone | `lib/milestone.cjs` | マイルストーンアーカイブ、要件マーキング | +| Commands | `lib/commands.cjs` | その他: slug、タイムスタンプ、TODO、scaffold、統計、Web 検索 | +| Model Profiles | `lib/model-profiles.cjs` | プロファイル解決テーブル | +| UAT | `lib/uat.cjs` | 全フェーズ横断 UAT/検証監査 | +| Profile Output | `lib/profile-output.cjs` | 開発者プロファイルのフォーマット | +| Profile Pipeline | `lib/profile-pipeline.cjs` | セッション分析パイプライン | diff --git a/gsd-opencode/docs/ja-JP/COMMANDS.md b/gsd-opencode/docs/ja-JP/COMMANDS.md new file mode 100644 index 0000000..f2268f6 --- /dev/null +++ b/gsd-opencode/docs/ja-JP/COMMANDS.md @@ -0,0 +1,933 @@ +# GSD コマンドリファレンス + +> コマンド構文、フラグ、オプション、使用例の完全なリファレンスです。機能の詳細については[機能リファレンス](FEATURES.md)を、ワークフローのチュートリアルについては[ユーザーガイド](USER-GUIDE.md)をご覧ください。 + +--- + +## コマンド構文 + +- **OpenCode / Gemini / Copilot:** `/gsd-command-name [args]` +- **OpenCode:** `/gsd-command-name [args]` +- **Codex:** `$gsd-command-name [args]` + +--- + +## コアワークフローコマンド + +### `/gsd-new-project` + +詳細なコンテキスト収集を行い、新しいプロジェクトを初期化します。 + +| フラグ | 説明 | +|------|-------------| +| `--auto @file.md` | ドキュメントから自動抽出し、対話的な質問をスキップ | + +**前提条件:** 既存の `.planning/PROJECT.md` がないこと +**生成物:** `PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md`、`STATE.md`、`config.json`、`research/`、`AGENTS.md` + +```bash +/gsd-new-project # 対話モード +/gsd-new-project --auto @prd.md # PRDから自動抽出 +``` + +--- + +### `/gsd-new-workspace` + +リポジトリのコピーと独立した `.planning/` ディレクトリを持つ分離されたワークスペースを作成します。 + +| フラグ | 説明 | +|------|-------------| +| `--name ` | ワークスペース名（必須） | +| `--repos repo1,repo2` | カンマ区切りのリポジトリパスまたは名前 | +| `--path /target` | 対象ディレクトリ（デフォルト: `~/gsd-workspaces/`） | +| `--strategy worktree\|clone` | コピー戦略（デフォルト: `worktree`） | +| `--branch ` | チェックアウトするブランチ（デフォルト: `workspace/`） | +| `--auto` | 対話的な質問をスキップ | + +**ユースケース:** +- マルチリポ: リポジトリのサブセットを分離されたGSD状態で作業 +- 機能の分離: `--repos .` で現在のリポジトリのworktreeを作成 + +**生成物:** `WORKSPACE.md`、`.planning/`、リポジトリコピー（worktreeまたはclone） + +```bash +/gsd-new-workspace --name feature-b --repos hr-ui,ZeymoAPI +/gsd-new-workspace --name feature-b --repos . --strategy worktree # 同一リポジトリの分離 +/gsd-new-workspace --name spike --repos api,web --strategy clone # フルクローン +``` + +--- + +### `/gsd-list-workspaces` + +アクティブなGSDワークスペースとそのステータスを一覧表示します。 + +**スキャン対象:** `~/gsd-workspaces/` 内の `WORKSPACE.md` マニフェスト +**表示内容:** 名前、リポジトリ数、戦略、GSDプロジェクトのステータス + +```bash +/gsd-list-workspaces +``` + +--- + +### `/gsd-remove-workspace` + +ワークスペースを削除し、git worktreeをクリーンアップします。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `` | はい | 削除するワークスペース名 | + +**安全性:** コミットされていない変更があるリポジトリの削除を拒否します。名前の確認が必要です。 + +```bash +/gsd-remove-workspace feature-b +``` + +--- + +### `/gsd-discuss-phase` + +計画の前に実装に関する意思決定を記録します。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `N` | いいえ | フェーズ番号（デフォルトは現在のフェーズ） | + +| フラグ | 説明 | +|------|-------------| +| `--auto` | すべての質問で推奨デフォルトを自動選択 | +| `--batch` | 質問を一つずつではなくバッチ取り込みでグループ化 | +| `--analyze` | ディスカッション中にトレードオフ分析を追加 | + +**前提条件:** `.planning/ROADMAP.md` が存在すること +**生成物:** `{phase}-CONTEXT.md`、`{phase}-DISCUSSION-LOG.md`（監査証跡） + +```bash +/gsd-discuss-phase 1 # フェーズ1の対話的ディスカッション +/gsd-discuss-phase 3 --auto # フェーズ3でデフォルトを自動選択 +/gsd-discuss-phase --batch # 現在のフェーズのバッチモード +/gsd-discuss-phase 2 --analyze # トレードオフ分析付きディスカッション +``` + +--- + +### `/gsd-ui-phase` + +フロントエンドフェーズのUIデザイン契約書を生成します。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `N` | いいえ | フェーズ番号（デフォルトは現在のフェーズ） | + +**前提条件:** `.planning/ROADMAP.md` が存在し、フェーズにフロントエンド/UI作業があること +**生成物:** `{phase}-UI-SPEC.md` + +```bash +/gsd-ui-phase 2 # フェーズ2のデザイン契約書 +``` + +--- + +### `/gsd-plan-phase` + +フェーズの調査、計画、検証を行います。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `N` | いいえ | フェーズ番号（デフォルトは次の未計画フェーズ） | + +| フラグ | 説明 | +|------|-------------| +| `--auto` | 対話的な確認をスキップ | +| `--research` | RESEARCH.mdが存在しても強制的に再調査 | +| `--skip-research` | ドメイン調査ステップをスキップ | +| `--gaps` | ギャップ解消モード（VERIFICATION.mdを読み込み、調査をスキップ） | +| `--skip-verify` | プランチェッカーの検証ループをスキップ | +| `--prd ` | discuss-phaseの代わりにPRDファイルをコンテキストとして使用 | +| `--reviews` | REVIEWS.mdのクロスAIレビューフィードバックで再計画 | + +**前提条件:** `.planning/ROADMAP.md` が存在すること +**生成物:** `{phase}-RESEARCH.md`、`{phase}-{N}-PLAN.md`、`{phase}-VALIDATION.md` + +```bash +/gsd-plan-phase 1 # フェーズ1の調査＋計画＋検証 +/gsd-plan-phase 3 --skip-research # 調査なしで計画（馴染みのあるドメイン） +/gsd-plan-phase --auto # 非対話型の計画 +``` + +--- + +### `/gsd-execute-phase` + +フェーズ内のすべてのプランをウェーブベースの並列化で実行するか、特定のウェーブを実行します。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `N` | **はい** | 実行するフェーズ番号 | +| `--wave N` | いいえ | フェーズ内のウェーブ `N` のみを実行 | + +**前提条件:** フェーズにPLAN.mdファイルがあること +**生成物:** プランごとの `{phase}-{N}-SUMMARY.md`、gitコミット、フェーズ完了時に `{phase}-VERIFICATION.md` + +```bash +/gsd-execute-phase 1 # フェーズ1を実行 +/gsd-execute-phase 1 --wave 2 # ウェーブ2のみを実行 +``` + +--- + +### `/gsd-verify-work` + +自動診断付きのユーザー受入テスト。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `N` | いいえ | フェーズ番号（デフォルトは最後に実行されたフェーズ） | + +**前提条件:** フェーズが実行済みであること +**生成物:** `{phase}-UAT.md`、問題が見つかった場合は修正プラン + +```bash +/gsd-verify-work 1 # フェーズ1のUAT +``` + +--- + +### `/gsd-next` + +次の論理的なワークフローステップに自動的に進みます。プロジェクトの状態を読み取り、適切なコマンドを実行します。 + +**前提条件:** `.planning/` ディレクトリが存在すること +**動作:** +- プロジェクトなし → `/gsd-new-project` を提案 +- フェーズにディスカッションが必要 → `/gsd-discuss-phase` を実行 +- フェーズに計画が必要 → `/gsd-plan-phase` を実行 +- フェーズに実行が必要 → `/gsd-execute-phase` を実行 +- フェーズに検証が必要 → `/gsd-verify-work` を実行 +- 全フェーズ完了 → `/gsd-complete-milestone` を提案 + +```bash +/gsd-next # 次のステップを自動検出して実行 +``` + +--- + +### `/gsd-session-report` + +作業サマリー、成果、推定リソース使用量を含むセッションレポートを生成します。 + +**前提条件:** 直近の作業があるアクティブなプロジェクト +**生成物:** `.planning/reports/SESSION_REPORT.md` + +```bash +/gsd-session-report # セッション後のサマリーを生成 +``` + +**レポートに含まれる内容:** +- 実施した作業（コミット、実行したプラン、進行したフェーズ） +- 成果と成果物 +- ブロッカーと意思決定 +- 推定トークン/コスト使用量 +- 次のステップの推奨事項 + +--- + +### `/gsd-ship` + +完了したフェーズの作業から自動生成された本文でPRを作成します。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `N` | いいえ | フェーズ番号またはマイルストーンバージョン（例: `4` または `v1.0`） | +| `--draft` | いいえ | ドラフトPRとして作成 | + +**前提条件:** フェーズが検証済み（`/gsd-verify-work` が合格）、`gh` CLIがインストールされ認証済みであること +**生成物:** 計画アーティファクトからリッチな本文を持つGitHub PR、STATE.mdの更新 + +```bash +/gsd-ship 4 # フェーズ4をシップ +/gsd-ship 4 --draft # ドラフトPRとしてシップ +``` + +**PR本文に含まれる内容:** +- ROADMAP.mdからのフェーズ目標 +- SUMMARY.mdファイルからの変更サマリー +- 対応した要件（REQ-ID） +- 検証ステータス +- 主要な意思決定 + +--- + +### `/gsd-ui-review` + +実装済みフロントエンドの事後的な6軸ビジュアル監査。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `N` | いいえ | フェーズ番号（デフォルトは最後に実行されたフェーズ） | + +**前提条件:** プロジェクトにフロントエンドコードがあること（単体で動作、GSDプロジェクト不要） +**生成物:** `{phase}-UI-REVIEW.md`、`.planning/ui-reviews/` 内のスクリーンショット + +```bash +/gsd-ui-review # 現在のフェーズを監査 +/gsd-ui-review 3 # フェーズ3を監査 +``` + +--- + +### `/gsd-audit-uat` + +全フェーズを横断した未処理のUATおよび検証項目の監査。 + +**前提条件:** 少なくとも1つのフェーズがUATまたは検証付きで実行されていること +**生成物:** カテゴリ分類された監査レポートと人間用テストプラン + +```bash +/gsd-audit-uat +``` + +--- + +### `/gsd-audit-milestone` + +マイルストーンが完了定義を満たしたかを検証します。 + +**前提条件:** 全フェーズが実行済みであること +**生成物:** ギャップ分析付き監査レポート + +```bash +/gsd-audit-milestone +``` + +--- + +### `/gsd-complete-milestone` + +マイルストーンをアーカイブし、リリースをタグ付けします。 + +**前提条件:** マイルストーン監査が完了していること（推奨） +**生成物:** `MILESTONES.md` エントリ、gitタグ + +```bash +/gsd-complete-milestone +``` + +--- + +### `/gsd-milestone-summary` + +チームのオンボーディングやレビューのために、マイルストーンのアーティファクトから包括的なプロジェクトサマリーを生成します。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `version` | いいえ | マイルストーンバージョン（デフォルトは現在/最新のマイルストーン） | + +**前提条件:** 少なくとも1つの完了済みまたは進行中のマイルストーンがあること +**生成物:** `.planning/reports/MILESTONE_SUMMARY-v{version}.md` + +**サマリーに含まれる内容:** +- 概要、アーキテクチャの意思決定、フェーズごとの詳細分析 +- 主要な意思決定とトレードオフ +- 要件カバレッジ +- 技術的負債と先送り項目 +- 新しいチームメンバー向けのスタートガイド +- 生成後に対話的なQ&Aを提供 + +```bash +/gsd-milestone-summary # 現在のマイルストーンをサマリー +/gsd-milestone-summary v1.0 # 特定のマイルストーンをサマリー +``` + +--- + +### `/gsd-new-milestone` + +次のバージョンサイクルを開始します。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `name` | いいえ | マイルストーン名 | +| `--reset-phase-numbers` | いいえ | 新しいマイルストーンをフェーズ1から開始し、ロードマップ作成前に古いフェーズディレクトリをアーカイブ | + +**前提条件:** 前のマイルストーンが完了していること +**生成物:** 更新された `PROJECT.md`、新しい `REQUIREMENTS.md`、新しい `ROADMAP.md` + +```bash +/gsd-new-milestone # 対話モード +/gsd-new-milestone "v2.0 Mobile" # 名前付きマイルストーン +/gsd-new-milestone --reset-phase-numbers "v2.0 Mobile" # マイルストーン番号を1からリスタート +``` + +--- + +## フェーズ管理コマンド + +### `/gsd-add-phase` + +ロードマップに新しいフェーズを追加します。 + +```bash +/gsd-add-phase # 対話型 — フェーズの説明を入力 +``` + +### `/gsd-insert-phase` + +小数番号を使用して、フェーズ間に緊急の作業を挿入します。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `N` | いいえ | このフェーズ番号の後に挿入 | + +```bash +/gsd-insert-phase 3 # フェーズ3と4の間に挿入 → 3.1を作成 +``` + +### `/gsd-remove-phase` + +将来のフェーズを削除し、後続のフェーズの番号を振り直します。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `N` | いいえ | 削除するフェーズ番号 | + +```bash +/gsd-remove-phase 7 # フェーズ7を削除、8→7、9→8等に番号振り直し +``` + +### `/gsd-list-phase-assumptions` + +計画前にOpenCodeの意図するアプローチをプレビューします。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `N` | いいえ | フェーズ番号 | + +```bash +/gsd-list-phase-assumptions 2 # フェーズ2の前提を確認 +``` + +### `/gsd-plan-milestone-gaps` + +マイルストーン監査のギャップを解消するフェーズを作成します。 + +```bash +/gsd-plan-milestone-gaps # 各監査ギャップに対してフェーズを作成 +``` + +### `/gsd-research-phase` + +詳細なエコシステム調査のみを実行します（単体機能 — 通常は `/gsd-plan-phase` を使用してください）。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `N` | いいえ | フェーズ番号 | + +```bash +/gsd-research-phase 4 # フェーズ4のドメインを調査 +``` + +### `/gsd-validate-phase` + +遡及的にNyquistバリデーションのギャップを監査・補填します。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `N` | いいえ | フェーズ番号 | + +```bash +/gsd-validate-phase 2 # フェーズ2のテストカバレッジを監査 +``` + +--- + +## ナビゲーションコマンド + +### `/gsd-progress` + +ステータスと次のステップを表示します。 + +```bash +/gsd-progress # "今どこにいる？次は何？" +``` + +### `/gsd-resume-work` + +前回のセッションから完全なコンテキストを復元します。 + +```bash +/gsd-resume-work # コンテキストリセットまたは新しいセッション後に使用 +``` + +### `/gsd-pause-work` + +フェーズの途中で中断する際にコンテキストのハンドオフを保存します。 + +```bash +/gsd-pause-work # continue-here.mdを作成 +``` + +### `/gsd-manager` + +1つのターミナルから複数のフェーズを管理する対話的なコマンドセンター。 + +**前提条件:** `.planning/ROADMAP.md` が存在すること +**動作:** +- 全フェーズのビジュアルステータスインジケータ付きダッシュボード +- 依存関係と進捗に基づいた最適な次のアクションを推奨 +- 作業のディスパッチ: discussはインラインで実行、plan/executeはバックグラウンドエージェントとして実行 +- 1つのターミナルから複数フェーズの作業を並列化するパワーユーザー向け + +```bash +/gsd-manager # コマンドセンターダッシュボードを開く +``` + +--- + +### `/gsd-help` + +すべてのコマンドと使用ガイドを表示します。 + +```bash +/gsd-help # クイックリファレンス +``` + +--- + +## ユーティリティコマンド + +### `/gsd-quick` + +GSDの保証付きでアドホックタスクを実行します。 + +| フラグ | 説明 | +|------|-------------| +| `--full` | プランチェック（2回のイテレーション）＋実行後検証を有効化 | +| `--discuss` | 軽量な事前計画ディスカッション | +| `--research` | 計画前にフォーカスされたリサーチャーを起動 | + +フラグは組み合わせ可能です。 + +```bash +/gsd-quick # 基本的なクイックタスク +/gsd-quick --discuss --research # ディスカッション＋調査＋計画 +/gsd-quick --full # プランチェックと検証付き +/gsd-quick --discuss --research --full # すべてのオプションステージ +``` + +### `/gsd-autonomous` + +残りのすべてのフェーズを自律的に実行します。 + +| フラグ | 説明 | +|------|-------------| +| `--from N` | 特定のフェーズ番号から開始 | + +```bash +/gsd-autonomous # 残りの全フェーズを実行 +/gsd-autonomous --from 3 # フェーズ3から開始 +``` + +### `/gsd-do` + +フリーテキストを適切なGSDコマンドにルーティングします。 + +```bash +/gsd-do # その後、やりたいことを説明 +``` + +### `/gsd-note` + +手軽にアイデアをキャプチャ — メモの追加、一覧表示、またはTodoへの昇格。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `text` | いいえ | キャプチャするメモテキスト（デフォルト: 追加モード） | +| `list` | いいえ | プロジェクトおよびグローバルスコープからすべてのメモを一覧表示 | +| `promote N` | いいえ | メモNを構造化されたTodoに変換 | + +| フラグ | 説明 | +|------|-------------| +| `--global` | メモ操作にグローバルスコープを使用 | + +```bash +/gsd-note "Consider caching strategy for API responses" +/gsd-note list +/gsd-note promote 3 +``` + +### `/gsd-debug` + +永続的な状態を持つ体系的なデバッグ。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `description` | いいえ | バグの説明 | + +```bash +/gsd-debug "Login button not responding on mobile Safari" +``` + +### `/gsd-add-todo` + +後で取り組むアイデアやタスクをキャプチャします。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `description` | いいえ | Todoの説明 | + +```bash +/gsd-add-todo "Consider adding dark mode support" +``` + +### `/gsd-check-todos` + +保留中のTodoを一覧表示し、取り組むものを選択します。 + +```bash +/gsd-check-todos +``` + +### `/gsd-add-tests` + +完了したフェーズのテストを生成します。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `N` | いいえ | フェーズ番号 | + +```bash +/gsd-add-tests 2 # フェーズ2のテストを生成 +``` + +### `/gsd-stats` + +プロジェクトの統計情報を表示します。 + +```bash +/gsd-stats # プロジェクトメトリクスダッシュボード +``` + +### `/gsd-profile-user` + +OpenCodeのセッション分析から8つの次元（コミュニケーションスタイル、意思決定パターン、デバッグアプローチ、UXプリファレンス、ベンダー選択、フラストレーションのトリガー、学習スタイル、説明の深さ）にわたる開発者行動プロファイルを生成します。OpenCodeのレスポンスをパーソナライズするアーティファクトを生成します。 + +| フラグ | 説明 | +|------|-------------| +| `--questionnaire` | セッション分析の代わりに対話型アンケートを使用 | +| `--refresh` | セッションを再分析してプロファイルを再生成 | + +**生成されるアーティファクト:** +- `USER-PROFILE.md` — 完全な行動プロファイル +- `/gsd-dev-preferences` コマンド — 任意のセッションでプリファレンスをロード +- `AGENTS.md` プロファイルセクション — OpenCodeが自動検出 + +```bash +/gsd-profile-user # セッションを分析してプロファイルを構築 +/gsd-profile-user --questionnaire # 対話型アンケートのフォールバック +/gsd-profile-user --refresh # 新鮮な分析からの再生成 +``` + +### `/gsd-health` + +`.planning/` ディレクトリの整合性を検証します。 + +| フラグ | 説明 | +|------|-------------| +| `--repair` | 回復可能な問題を自動修復 | + +```bash +/gsd-health # 整合性チェック +/gsd-health --repair # チェックして修復 +``` + +### `/gsd-cleanup` + +完了したマイルストーンの蓄積されたフェーズディレクトリをアーカイブします。 + +```bash +/gsd-cleanup +``` + +--- + +## 診断コマンド + +### `/gsd-forensics` + +失敗またはスタックしたGSDワークフローの事後調査。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `description` | いいえ | 問題の説明（省略時はプロンプトで入力） | + +**前提条件:** `.planning/` ディレクトリが存在すること +**生成物:** `.planning/forensics/report-{timestamp}.md` + +**調査の対象:** +- Git履歴分析（直近のコミット、スタックパターン、時間的ギャップ） +- アーティファクトの整合性（完了フェーズで期待されるファイル） +- STATE.mdの異常とセッション履歴 +- コミットされていない作業、コンフリクト、放棄された変更 +- 少なくとも4種類の異常をチェック（スタックループ、欠損アーティファクト、放棄された作業、クラッシュ/中断） +- アクション可能な所見がある場合、GitHubイシューの作成を提案 + +```bash +/gsd-forensics # 対話型 — 問題の入力を促す +/gsd-forensics "Phase 3 execution stalled" # 問題の説明付き +``` + +--- + +## ワークストリーム管理 + +### `/gsd-workstreams` + +マイルストーンの異なる領域で並行作業するためのワークストリームを管理します。 + +**サブコマンド:** + +| サブコマンド | 説明 | +|------------|-------------| +| `list` | すべてのワークストリームをステータス付きで一覧表示（サブコマンド未指定時のデフォルト） | +| `create ` | 新しいワークストリームを作成 | +| `status ` | 1つのワークストリームの詳細ステータス | +| `switch ` | アクティブなワークストリームを設定 | +| `progress` | 全ワークストリームの進捗サマリー | +| `complete ` | 完了したワークストリームをアーカイブ | +| `resume ` | ワークストリームでの作業を再開 | + +**前提条件:** アクティブなGSDプロジェクト +**生成物:** `.planning/` 配下のワークストリームディレクトリ、ワークストリームごとの状態追跡 + +```bash +/gsd-workstreams # すべてのワークストリームを一覧表示 +/gsd-workstreams create backend-api # 新しいワークストリームを作成 +/gsd-workstreams switch backend-api # アクティブなワークストリームを設定 +/gsd-workstreams status backend-api # 詳細ステータス +/gsd-workstreams progress # ワークストリーム横断の進捗概要 +/gsd-workstreams complete backend-api # 完了したワークストリームをアーカイブ +/gsd-workstreams resume backend-api # ワークストリームでの作業を再開 +``` + +--- + +## 設定コマンド + +### `/gsd-settings` + +ワークフロートグルとモデルプロファイルの対話的な設定。 + +```bash +/gsd-settings # 対話型設定 +``` + +### `/gsd-set-profile` + +クイックプロファイル切り替え。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `profile` | **はい** | `quality`、`balanced`、`budget`、または `inherit` | + +```bash +/gsd-set-profile budget # budgetプロファイルに切り替え +/gsd-set-profile quality # qualityプロファイルに切り替え +``` + +--- + +## ブラウンフィールドコマンド + +### `/gsd-map-codebase` + +並列マッパーエージェントで既存のコードベースを分析します。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `area` | いいえ | マッピングを特定の領域にスコープ | + +```bash +/gsd-map-codebase # コードベース全体を分析 +/gsd-map-codebase auth # auth領域にフォーカス +``` + +--- + +## アップデートコマンド + +### `/gsd-update` + +変更履歴のプレビュー付きでGSDをアップデートします。 + +```bash +/gsd-update # アップデートを確認してインストール +``` + +### `/gsd-reapply-patches` + +GSDアップデート後にローカルの変更を復元します。 + +```bash +/gsd-reapply-patches # ローカルの変更をマージバック +``` + +--- + +## 高速＆インラインコマンド + +### `/gsd-fast` + +簡単なタスクをインラインで実行 — サブエージェントなし、計画のオーバーヘッドなし。タイポ修正、設定変更、小さなリファクタリング、忘れたコミットなどに最適。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `task description` | いいえ | 実行する内容（省略時はプロンプトで入力） | + +**`/gsd-quick` の代替ではありません** — 調査、複数ステップの計画、または検証が必要な場合は `/gsd-quick` を使用してください。 + +```bash +/gsd-fast "fix typo in README" +/gsd-fast "add .env to gitignore" +``` + +--- + +## コード品質コマンド + +### `/gsd-review` + +外部AI CLIからのフェーズプランのクロスAIピアレビュー。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `--phase N` | **はい** | レビューするフェーズ番号 | + +| フラグ | 説明 | +|------|-------------| +| `--gemini` | Gemini CLIレビューを含める | +| `--OpenCode` | OpenCode CLIレビューを含める（別セッション） | +| `--codex` | Codex CLIレビューを含める | +| `--all` | 利用可能なすべてのCLIを含める | + +**生成物:** `{phase}-REVIEWS.md` — `/gsd-plan-phase --reviews` で利用可能 + +```bash +/gsd-review --phase 3 --all +/gsd-review --phase 2 --gemini +``` + +--- + +### `/gsd-pr-branch` + +`.planning/` のコミットをフィルタリングしてクリーンなPRブランチを作成します。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `target branch` | いいえ | ベースブランチ（デフォルト: `main`） | + +**目的:** レビュアーにはコード変更のみを表示し、GSD計画アーティファクトは含めません。 + +```bash +/gsd-pr-branch # mainに対してフィルタリング +/gsd-pr-branch develop # developに対してフィルタリング +``` + +--- + +### `/gsd-audit-uat` + +全フェーズを横断した未処理のUATおよび検証項目の監査。 + +**前提条件:** 少なくとも1つのフェーズがUATまたは検証付きで実行されていること +**生成物:** カテゴリ分類された監査レポートと人間用テストプラン + +```bash +/gsd-audit-uat +``` + +--- + +## バックログ＆スレッドコマンド + +### `/gsd-add-backlog` + +999.x番号付けを使用して、バックログのパーキングロットにアイデアを追加します。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `description` | **はい** | バックログ項目の説明 | + +**999.x番号付け**により、バックログ項目はアクティブなフェーズシーケンスの外に保持されます。フェーズディレクトリは即座に作成されるため、`/gsd-discuss-phase` や `/gsd-plan-phase` がそれらに対して動作します。 + +```bash +/gsd-add-backlog "GraphQL API layer" +/gsd-add-backlog "Mobile responsive redesign" +``` + +--- + +### `/gsd-review-backlog` + +バックログ項目をレビューし、アクティブなマイルストーンに昇格させます。 + +**項目ごとのアクション:** 昇格（アクティブシーケンスに移動）、保持（バックログに残す）、削除。 + +```bash +/gsd-review-backlog +``` + +--- + +### `/gsd-plant-seed` + +トリガー条件付きの将来のアイデアをキャプチャ — 適切なマイルストーンで自動的に表面化します。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| `idea summary` | いいえ | シードの説明（省略時はプロンプトで入力） | + +シードはコンテキストの劣化を解決します：誰も読まないDeferredの一行メモの代わりに、シードは完全なWHY、いつ表面化すべきか、詳細への手がかりを保存します。 + +**生成物:** `.planning/seeds/SEED-NNN-slug.md` +**利用先:** `/gsd-new-milestone`（シードをスキャンしてマッチするものを提示） + +```bash +/gsd-plant-seed "Add real-time collaboration when WebSocket infra is in place" +``` + +--- + +### `/gsd-thread` + +クロスセッション作業のための永続的なコンテキストスレッドを管理します。 + +| 引数 | 必須 | 説明 | +|----------|----------|-------------| +| （なし） | — | すべてのスレッドを一覧表示 | +| `name` | — | 名前で既存のスレッドを再開 | +| `description` | — | 新しいスレッドを作成 | + +スレッドは、複数のセッションにまたがるが特定のフェーズに属さない作業のための軽量なクロスセッション知識ストアです。`/gsd-pause-work` よりも軽量です。 + +```bash +/gsd-thread # すべてのスレッドを一覧表示 +/gsd-thread fix-deploy-key-auth # スレッドを再開 +/gsd-thread "Investigate TCP timeout in pasta service" # 新規作成 +``` + +--- + +## コミュニティコマンド + +### `/gsd-join-discord` + +Discordコミュニティの招待を開きます。 + +```bash +/gsd-join-discord +``` diff --git a/gsd-opencode/docs/ja-JP/CONFIGURATION.md b/gsd-opencode/docs/ja-JP/CONFIGURATION.md new file mode 100644 index 0000000..5dc88f3 --- /dev/null +++ b/gsd-opencode/docs/ja-JP/CONFIGURATION.md @@ -0,0 +1,342 @@ +# GSD 設定リファレンス + +> 設定スキーマの全容、ワークフロートグル、モデルプロファイル、Git ブランチオプション。機能の詳細については[機能リファレンス](FEATURES.md)を参照してください。 + +--- + +## 設定ファイル + +GSD はプロジェクト設定を `.planning/config.json` に保存します。`/gsd-new-project` 実行時に作成され、`/gsd-settings` で更新できます。 + +### 完全スキーマ + +```json +{ + "mode": "interactive", + "granularity": "standard", + "model_profile": "balanced", + "model_overrides": {}, + "planning": { + "commit_docs": true, + "search_gitignored": false + }, + "workflow": { + "research": true, + "plan_check": true, + "verifier": true, + "auto_advance": false, + "nyquist_validation": true, + "ui_phase": true, + "ui_safety_gate": true, + "node_repair": true, + "node_repair_budget": 2, + "research_before_questions": false, + "discuss_mode": "discuss", + "skip_discuss": false, + "text_mode": false + }, + "hooks": { + "context_warnings": true, + "workflow_guard": false + }, + "parallelization": { + "enabled": true, + "plan_level": true, + "task_level": false, + "skip_checkpoints": true, + "max_concurrent_agents": 3, + "min_plans_for_parallel": 2 + }, + "git": { + "branching_strategy": "none", + "phase_branch_template": "gsd/phase-{phase}-{slug}", + "milestone_branch_template": "gsd/{milestone}-{slug}", + "quick_branch_template": null + }, + "gates": { + "confirm_project": true, + "confirm_phases": true, + "confirm_roadmap": true, + "confirm_breakdown": true, + "confirm_plan": true, + "execute_next_plan": true, + "issues_review": true, + "confirm_transition": true + }, + "safety": { + "always_confirm_destructive": true, + "always_confirm_external_services": true + } +} +``` + +--- + +## コア設定 + +| 設定 | 型 | 選択肢 | デフォルト | 説明 | +|------|-----|--------|-----------|------| +| `mode` | enum | `interactive`, `yolo` | `interactive` | `yolo` は判断を自動承認、`interactive` は各ステップで確認 | +| `granularity` | enum | `coarse`, `standard`, `fine` | `standard` | フェーズ数を制御: `coarse`（3〜5）、`standard`（5〜8）、`fine`（8〜12） | +| `model_profile` | enum | `quality`, `balanced`, `budget`, `inherit` | `balanced` | 各エージェントのモデルティア（[モデルプロファイル](#モデルプロファイル)を参照） | + +> **注意:** `granularity` は v1.22.3 で `depth` から改名されました。既存の設定は自動的に移行されます。 + +--- + +## ワークフロートグル + +すべてのワークフロートグルは **未設定 = 有効** のパターンに従います。config にキーが存在しない場合、デフォルトは `true` になります。 + +| 設定 | 型 | デフォルト | 説明 | +|------|-----|-----------|------| +| `workflow.research` | boolean | `true` | 各フェーズの計画前にドメイン調査を実施 | +| `workflow.plan_check` | boolean | `true` | プラン検証ループ（最大3回の反復） | +| `workflow.verifier` | boolean | `true` | 実行後にフェーズ目標に対する検証を実施 | +| `workflow.auto_advance` | boolean | `false` | discuss → plan → execute を停止せずに自動連鎖 | +| `workflow.nyquist_validation` | boolean | `true` | plan-phase のリサーチ中にテストカバレッジマッピングを実施 | +| `workflow.ui_phase` | boolean | `true` | フロントエンドフェーズで UI デザインコントラクトを生成 | +| `workflow.ui_safety_gate` | boolean | `true` | plan-phase 中にフロントエンドフェーズに対して /gsd-ui-phase の実行を促すプロンプトを表示 | +| `workflow.node_repair` | boolean | `true` | 検証失敗時にタスクを自律的に修復 | +| `workflow.node_repair_budget` | number | `2` | 失敗タスクあたりの最大修復試行回数 | +| `workflow.research_before_questions` | boolean | `false` | ディスカッション質問の後ではなく前にリサーチを実行 | +| `workflow.discuss_mode` | string | `'discuss'` | `/gsd-discuss-phase` のコンテキスト収集方法を制御。`'discuss'`（デフォルト）は質問を1つずつ行います。`'assumptions'` はまずコードベースを読み取り、信頼度レベル付きの構造化された仮説を生成し、誤っている点のみ修正を求めます。v1.28 で追加 | +| `workflow.skip_discuss` | boolean | `false` | `true` の場合、`/gsd-autonomous` は discuss-phase を完全にスキップし、ROADMAP のフェーズ目標から最小限の CONTEXT.md を作成します。開発者の要望が PROJECT.md/REQUIREMENTS.md に十分に記載されているプロジェクトに適しています。v1.28 で追加 | +| `workflow.text_mode` | boolean | `false` | question の TUI メニューをプレーンテキストの番号付きリストに置き換えます。TUI メニューが表示されない OpenCode リモートセッション（`/rc` モード）で必要です。discuss-phase で `--text` フラグを使用してセッションごとに設定することもできます。v1.28 で追加 | + +### 推奨プリセット + +| シナリオ | mode | granularity | profile | research | plan_check | verifier | +|---------|------|-------------|---------|----------|------------|----------| +| プロトタイピング | `yolo` | `coarse` | `budget` | `false` | `false` | `false` | +| 通常の開発 | `interactive` | `standard` | `balanced` | `true` | `true` | `true` | +| 本番リリース | `interactive` | `fine` | `quality` | `true` | `true` | `true` | + +--- + +## プランニング設定 + +| 設定 | 型 | デフォルト | 説明 | +|------|-----|-----------|------| +| `planning.commit_docs` | boolean | `true` | `.planning/` ファイルを git にコミットするかどうか | +| `planning.search_gitignored` | boolean | `false` | `.planning/` を含めるために広範な検索に `--no-ignore` を追加 | + +### 自動検出 + +`.planning/` が `.gitignore` に含まれている場合、config.json の設定に関係なく `commit_docs` は自動的に `false` になります。これにより git エラーが防止されます。 + +--- + +## フック設定 + +| 設定 | 型 | デフォルト | 説明 | +|------|-----|-----------|------| +| `hooks.context_warnings` | boolean | `true` | コンテキストモニターフックによるコンテキストウィンドウ使用量の警告を表示 | +| `hooks.workflow_guard` | boolean | `false` | GSD ワークフローのコンテキスト外でファイル編集が行われた場合に警告（`/gsd-quick` または `/gsd-fast` の使用を推奨） | + +プロンプトインジェクションガードフック（`gsd-prompt-guard.js`）は常に有効であり、無効にすることはできません。これはワークフロートグルではなく、セキュリティ機能です。 + +### プライベートプランニングのセットアップ + +プランニング成果物を git から除外するには： + +1. `planning.commit_docs: false` と `planning.search_gitignored: true` を設定 +2. `.planning/` を `.gitignore` に追加 +3. 既にトラッキング済みの場合: `git rm -r --cached .planning/ && git commit -m "chore: stop tracking planning docs"` + +--- + +## 並列化設定 + +| 設定 | 型 | デフォルト | 説明 | +|------|-----|-----------|------| +| `parallelization.enabled` | boolean | `true` | 独立したプランを同時に実行 | +| `parallelization.plan_level` | boolean | `true` | プランレベルで並列化 | +| `parallelization.task_level` | boolean | `false` | プラン内のタスクを並列化 | +| `parallelization.skip_checkpoints` | boolean | `true` | 並列実行中にチェックポイントをスキップ | +| `parallelization.max_concurrent_agents` | number | `3` | 同時実行エージェントの最大数 | +| `parallelization.min_plans_for_parallel` | number | `2` | 並列実行をトリガーする最小プラン数 | + +> **pre-commit フックと並列実行について**: 並列化が有効な場合、executor エージェントはビルドロックの競合（例: Rust プロジェクトでの cargo lock の競合）を回避するために `--no-verify` でコミットします。オーケストレーターは各ウェーブの完了後にフックを1回検証します。STATE.md の書き込みはファイルレベルのロックで保護され、同時書き込みによる破損を防ぎます。コミットごとにフックを実行する必要がある場合は、`parallelization.enabled: false` に設定してください。 + +--- + +## Git ブランチ + +| 設定 | 型 | デフォルト | 説明 | +|------|-----|-----------|------| +| `git.branching_strategy` | enum | `none` | `none`、`phase`、または `milestone` | +| `git.phase_branch_template` | string | `gsd/phase-{phase}-{slug}` | phase 戦略のブランチ名テンプレート | +| `git.milestone_branch_template` | string | `gsd/{milestone}-{slug}` | milestone 戦略のブランチ名テンプレート | +| `git.quick_branch_template` | string or null | `null` | `/gsd-quick` タスク用のオプションのブランチ名テンプレート | + +### 戦略の比較 + +| 戦略 | ブランチ作成 | スコープ | マージポイント | 適したケース | +|------|------------|---------|--------------|-------------| +| `none` | なし | N/A | N/A | 個人開発、シンプルなプロジェクト | +| `phase` | `execute-phase` 開始時 | 1フェーズ | フェーズ後にユーザーがマージ | フェーズごとのコードレビュー、きめ細かいロールバック | +| `milestone` | 最初の `execute-phase` 時 | マイルストーン内の全フェーズ | `complete-milestone` 時 | リリースブランチ、バージョンごとの PR | + +### テンプレート変数 + +| 変数 | 使用可能な場所 | 例 | +|------|--------------|-----| +| `{phase}` | `phase_branch_template` | `03`（ゼロパディング） | +| `{slug}` | 両方のテンプレート | `user-authentication`（小文字、ハイフン区切り） | +| `{milestone}` | `milestone_branch_template` | `v1.0` | +| `{num}` / `{quick}` | `quick_branch_template` | `260317-abc`（quick タスク ID） | + +quick タスクのブランチ設定例： + +```json +"git": { + "quick_branch_template": "gsd/quick-{num}-{slug}" +} +``` + +### マイルストーン完了時のマージオプション + +| オプション | Git コマンド | 結果 | +|-----------|-------------|------| +| スカッシュマージ（推奨） | `git merge --squash` | ブランチごとに1つのクリーンなコミット | +| 履歴付きマージ | `git merge --no-ff` | 個別のコミットをすべて保持 | +| マージせずに削除 | `git branch -D` | ブランチの作業を破棄 | +| ブランチを保持 | （なし） | 後で手動対応 | + +--- + +## ゲート設定 + +ワークフロー中の確認プロンプトを制御します。 + +| 設定 | 型 | デフォルト | 説明 | +|------|-----|-----------|------| +| `gates.confirm_project` | boolean | `true` | 確定前にプロジェクトの詳細を確認 | +| `gates.confirm_phases` | boolean | `true` | フェーズの分割を確認 | +| `gates.confirm_roadmap` | boolean | `true` | 続行前にロードマップを確認 | +| `gates.confirm_breakdown` | boolean | `true` | タスクの分割を確認 | +| `gates.confirm_plan` | boolean | `true` | 実行前に各プランを確認 | +| `gates.execute_next_plan` | boolean | `true` | 次のプラン実行前に確認 | +| `gates.issues_review` | boolean | `true` | 修正プラン作成前に課題をレビュー | +| `gates.confirm_transition` | boolean | `true` | フェーズ遷移を確認 | + +--- + +## セーフティ設定 + +| 設定 | 型 | デフォルト | 説明 | +|------|-----|-----------|------| +| `safety.always_confirm_destructive` | boolean | `true` | 破壊的操作（削除、上書き）の確認 | +| `safety.always_confirm_external_services` | boolean | `true` | 外部サービスとのやり取りの確認 | + +--- + +## フック設定 + +| 設定 | 型 | デフォルト | 説明 | +|------|-----|-----------|------| +| `hooks.context_warnings` | boolean | `true` | セッション中にコンテキストウィンドウの使用量警告を表示 | + +--- + +## モデルプロファイル + +### プロファイル定義 + +| エージェント | `quality` | `balanced` | `budget` | `inherit` | +|------------|-----------|------------|----------|-----------| +| gsd-planner | Opus | Opus | Sonnet | Inherit | +| gsd-roadmapper | Opus | Sonnet | Sonnet | Inherit | +| gsd-executor | Opus | Sonnet | Sonnet | Inherit | +| gsd-phase-researcher | Opus | Sonnet | Haiku | Inherit | +| gsd-project-researcher | Opus | Sonnet | Haiku | Inherit | +| gsd-research-synthesizer | Sonnet | Sonnet | Haiku | Inherit | +| gsd-debugger | Opus | Sonnet | Sonnet | Inherit | +| gsd-codebase-mapper | Sonnet | Haiku | Haiku | Inherit | +| gsd-verifier | Sonnet | Sonnet | Haiku | Inherit | +| gsd-plan-checker | Sonnet | Sonnet | Haiku | Inherit | +| gsd-integration-checker | Sonnet | Sonnet | Haiku | Inherit | +| gsd-nyquist-auditor | Sonnet | Sonnet | Haiku | Inherit | + +### エージェントごとのオーバーライド + +プロファイル全体を変更せずに特定のエージェントをオーバーライドできます： + +```json +{ + "model_profile": "balanced", + "model_overrides": { + "gsd-executor": "opus", + "gsd-planner": "haiku" + } +} +``` + +有効なオーバーライド値: `opus`、`sonnet`、`haiku`、`inherit`、または完全修飾モデル ID（例: `"openai/o3"`、`"google/gemini-2.5-pro"`）。 + +### 非 OpenCode ランタイム（Codex、OpenCode、Gemini CLI） + +GSD が非 OpenCode ランタイム向けにインストールされると、インストーラーは自動的に `~/.gsd/defaults.json` に `resolve_model_ids: "omit"` を設定します。これにより GSD はすべてのエージェントに対して空のモデルパラメータを返し、各エージェントはランタイムで設定されたモデルを使用します。デフォルトの場合、追加のセットアップは不要です。 + +異なるエージェントに異なるモデルを使用させたい場合は、ランタイムが認識する完全修飾モデル ID で `model_overrides` を使用してください： + +```json +{ + "resolve_model_ids": "omit", + "model_overrides": { + "gsd-planner": "o3", + "gsd-executor": "o4-mini", + "gsd-debugger": "o3", + "gsd-codebase-mapper": "o4-mini" + } +} +``` + +意図は OpenCode のプロファイルティアと同じです。計画やデバッグ（推論品質が最も重要な部分）にはより強力なモデルを使用し、実行やマッピング（プランに既に推論が含まれている部分）にはより安価なモデルを使用します。 + +**どのアプローチを使うべきか：** + +| シナリオ | 設定 | 効果 | +|---------|------|------| +| 非 OpenCode ランタイム、単一モデル | `resolve_model_ids: "omit"`（インストーラーのデフォルト） | すべてのエージェントがランタイムのデフォルトモデルを使用 | +| 非 OpenCode ランタイム、ティアードモデル | `resolve_model_ids: "omit"` + `model_overrides` | 指定されたエージェントは特定のモデルを使用、それ以外はランタイムのデフォルト | +| OpenCode + OpenRouter/ローカルプロバイダー | `model_profile: "inherit"` | すべてのエージェントがセッションモデルに従う | +| OpenCode + OpenRouter、ティアード | `model_profile: "inherit"` + `model_overrides` | 指定されたエージェントは特定のモデルを使用、それ以外は継承 | + +**`resolve_model_ids` の値：** + +| 値 | 動作 | 使用場面 | +|----|------|---------| +| `false`（デフォルト） | OpenCode エイリアス（`opus`、`sonnet`、`haiku`）を返す | OpenCode + ネイティブ Anthropic API | +| `true` | エイリアスを完全な OpenCode モデル ID（`OpenCode-opus-4-0`）にマッピング | 完全な ID が必要な API を使用する OpenCode | +| `"omit"` | 空文字列を返す（ランタイムがデフォルトを選択） | 非 OpenCode ランタイム（Codex、OpenCode、Gemini CLI） | + +### プロファイルの設計思想 + +| プロファイル | 設計思想 | 使用場面 | +|------------|---------|---------| +| `quality` | すべての意思決定に Opus、検証に Sonnet | クォータに余裕がある場合、重要なアーキテクチャ作業 | +| `balanced` | 計画のみ Opus、それ以外は Sonnet | 通常の開発（デフォルト） | +| `budget` | コード記述に Sonnet、リサーチ/検証に Haiku | 大量の作業、重要度の低いフェーズ | +| `inherit` | すべてのエージェントが現在のセッションモデルを使用 | 動的なモデル切り替え、**非 Anthropic プロバイダー**（OpenRouter、ローカルモデル） | + +--- + +## 環境変数 + +| 変数 | 用途 | +|------|------| +| `CLAUDE_CONFIG_DIR` | デフォルトの設定ディレクトリ（`$HOME/.config/opencode/`）をオーバーライド | +| `GEMINI_API_KEY` | コンテキストモニターがフックイベント名を切り替えるために検出 | +| `WSL_DISTRO_NAME` | インストーラーが WSL のパス処理のために検出 | + +--- + +## グローバルデフォルト + +将来のプロジェクト向けにグローバルデフォルトとして設定を保存できます。 + +**保存場所:** `~/.gsd/defaults.json` + +`/gsd-new-project` が新しい `config.json` を作成する際、グローバルデフォルトを読み込み、初期設定としてマージします。プロジェクトごとの設定は常にグローバル設定を上書きします。 diff --git a/gsd-opencode/docs/ja-JP/FEATURES.md b/gsd-opencode/docs/ja-JP/FEATURES.md new file mode 100644 index 0000000..d6b2586 --- /dev/null +++ b/gsd-opencode/docs/ja-JP/FEATURES.md @@ -0,0 +1,1290 @@ +# GSD 機能リファレンス + +> 全機能と要件の完全なドキュメントです。アーキテクチャの詳細については[アーキテクチャ](ARCHITECTURE.md)を、コマンド構文については[コマンドリファレンス](COMMANDS.md)をご覧ください。 + +--- + +## 目次 + +- [コア機能](#コア機能) + - [プロジェクト初期化](#1-プロジェクト初期化) + - [フェーズディスカッション](#2-フェーズディスカッション) + - [UI デザインコントラクト](#3-ui-デザインコントラクト) + - [フェーズプランニング](#4-フェーズプランニング) + - [フェーズ実行](#5-フェーズ実行) + - [作業検証](#6-作業検証) + - [UI レビュー](#7-ui-レビュー) + - [マイルストーン管理](#8-マイルストーン管理) +- [プランニング機能](#プランニング機能) + - [フェーズ管理](#9-フェーズ管理) + - [Quick モード](#10-quick-モード) + - [自律モード](#11-自律モード) + - [フリーフォームルーティング](#12-フリーフォームルーティング) + - [ノートキャプチャ](#13-ノートキャプチャ) + - [自動進行（Next）](#14-自動進行next) +- [品質保証機能](#品質保証機能) + - [Nyquist バリデーション](#15-nyquist-バリデーション) + - [プランチェック](#16-プランチェック) + - [実行後検証](#17-実行後検証) + - [ノードリペア](#18-ノードリペア) + - [ヘルスバリデーション](#19-ヘルスバリデーション) + - [クロスフェーズ回帰ゲート](#20-クロスフェーズ回帰ゲート) + - [要件カバレッジゲート](#21-要件カバレッジゲート) +- [コンテキストエンジニアリング機能](#コンテキストエンジニアリング機能) + - [コンテキストウィンドウ監視](#22-コンテキストウィンドウ監視) + - [セッション管理](#23-セッション管理) + - [セッションレポート](#24-セッションレポート) + - [マルチエージェントオーケストレーション](#25-マルチエージェントオーケストレーション) + - [モデルプロファイル](#26-モデルプロファイル) +- [ブラウンフィールド機能](#ブラウンフィールド機能) + - [コードベースマッピング](#27-コードベースマッピング) +- [ユーティリティ機能](#ユーティリティ機能) + - [デバッグシステム](#28-デバッグシステム) + - [Todo 管理](#29-todo-管理) + - [統計ダッシュボード](#30-統計ダッシュボード) + - [アップデートシステム](#31-アップデートシステム) + - [設定管理](#32-設定管理) + - [テスト生成](#33-テスト生成) +- [インフラストラクチャ機能](#インフラストラクチャ機能) + - [Git 連携](#34-git-連携) + - [CLI ツール](#35-cli-ツール) + - [マルチランタイムサポート](#36-マルチランタイムサポート) + - [フックシステム](#37-フックシステム) + - [開発者プロファイリング](#38-開発者プロファイリング) + - [実行ハードニング](#39-実行ハードニング) + - [検証デット追跡](#40-検証デット追跡) +- [v1.27 の機能](#v127-の機能) + - [Fast モード](#41-fast-モード) + - [クロス AI ピアレビュー](#42-クロス-ai-ピアレビュー) + - [バックログパーキングロット](#43-バックログパーキングロット) + - [永続コンテキストスレッド](#44-永続コンテキストスレッド) + - [PR ブランチフィルタリング](#45-pr-ブランチフィルタリング) + - [セキュリティハードニング](#46-セキュリティハードニング) + - [マルチリポワークスペースサポート](#47-マルチリポワークスペースサポート) + - [ディスカッション監査証跡](#48-ディスカッション監査証跡) +- [v1.28 の機能](#v128-の機能) + - [フォレンジクス](#49-フォレンジクス) + - [マイルストーンサマリー](#50-マイルストーンサマリー) + - [ワークストリームネームスペーシング](#51-ワークストリームネームスペーシング) + - [マネージャーダッシュボード](#52-マネージャーダッシュボード) + - [Assumptions ディスカッションモード](#53-assumptions-ディスカッションモード) + - [UI フェーズ自動検出](#54-ui-フェーズ自動検出) + - [マルチランタイムインストーラー選択](#55-マルチランタイムインストーラー選択) + +--- + +## コア機能 + +### 1. プロジェクト初期化 + +**コマンド:** `/gsd-new-project [--auto @file.md]` + +**目的:** ユーザーのアイデアを、リサーチ、スコープ化された要件、フェーズ分けされたロードマップを持つ完全に構造化されたプロジェクトに変換します。 + +**要件:** +- REQ-INIT-01: システムはプロジェクトスコープが完全に理解されるまで適応的な質問を実施しなければならない +- REQ-INIT-02: システムはドメインエコシステムを調査するために並列リサーチエージェントを起動しなければならない +- REQ-INIT-03: システムは要件を v1（必須）、v2（将来）、スコープ外のカテゴリに分類しなければならない +- REQ-INIT-04: システムは要件トレーサビリティ付きのフェーズ分けされたロードマップを生成しなければならない +- REQ-INIT-05: システムは続行前にロードマップのユーザー承認を要求しなければならない +- REQ-INIT-06: `.planning/PROJECT.md` が既に存在する場合、システムは再初期化を防止しなければならない +- REQ-INIT-07: システムは `--auto @file.md` フラグをサポートし、インタラクティブな質問をスキップしてドキュメントから情報を抽出しなければならない + +**生成物:** +| 成果物 | 説明 | +|--------|------| +| `PROJECT.md` | プロジェクトビジョン、制約、技術的決定、発展ルール | +| `REQUIREMENTS.md` | 一意の ID（REQ-XX）付きのスコープ化された要件 | +| `ROADMAP.md` | ステータス追跡と要件マッピング付きのフェーズ分割 | +| `STATE.md` | ポジション、決定事項、メトリクスを含む初期プロジェクト状態 | +| `config.json` | ワークフロー設定 | +| `research/SUMMARY.md` | 統合されたドメインリサーチ | +| `research/STACK.md` | 技術スタック調査 | +| `research/FEATURES.md` | 機能実装パターン | +| `research/ARCHITECTURE.md` | アーキテクチャパターンとトレードオフ | +| `research/PITFALLS.md` | よくある失敗パターンと対策 | + +**プロセス:** +1. **質問** — 「ドリーム抽出」の哲学に基づく適応的な質問（要件収集ではなく） +2. **リサーチ** — 4つの並列リサーチャーエージェントがスタック、機能、アーキテクチャ、落とし穴を調査 +3. **統合** — リサーチシンセサイザーが調査結果を SUMMARY.md に統合 +4. **要件** — ユーザーの回答とリサーチから要件を抽出し、スコープ別に分類 +5. **ロードマップ** — 要件にマッピングされたフェーズ分割、粒度設定によりフェーズ数を制御 + +**機能要件:** +- 質問は検出されたプロジェクトタイプ（Web アプリ、CLI、モバイル、API など）に応じて適応する +- リサーチエージェントは最新のエコシステム情報を取得するための Web 検索機能を持つ +- 粒度設定によりフェーズ数を制御: `coarse`（3-5）、`standard`（5-8）、`fine`（8-12） +- `--auto` モードではインタラクティブな質問なしで提供されたドキュメントからすべての情報を抽出 +- 既存のコードベースコンテキスト（`/gsd-map-codebase` から取得）がある場合は読み込む + +--- + +### 2. フェーズディスカッション + +**コマンド:** `/gsd-discuss-phase [N] [--auto] [--batch]` + +**目的:** リサーチとプランニング開始前に、ユーザーの実装に関する要望や決定事項を収集します。AI が推測する原因となるグレーゾーンを排除します。 + +**要件:** +- REQ-DISC-01: システムはフェーズのスコープを分析し、決定が必要な領域（グレーゾーン）を特定しなければならない +- REQ-DISC-02: システムはグレーゾーンをタイプ別に分類しなければならない（ビジュアル、API、コンテンツ、構成など） +- REQ-DISC-03: システムは過去の CONTEXT.md ファイルで既に回答済みの質問のみを除外しなければならない +- REQ-DISC-04: システムは決定事項を `{phase}-CONTEXT.md` に正規参照付きで永続化しなければならない +- REQ-DISC-05: システムは推奨デフォルトを自動選択する `--auto` フラグをサポートしなければならない +- REQ-DISC-06: システムはグループ化された質問取り込みのための `--batch` フラグをサポートしなければならない +- REQ-DISC-07: システムはグレーゾーンを特定する前に関連ソースファイルをスカウトしなければならない（コード認識型ディスカッション） + +**生成物:** `{padded_phase}-CONTEXT.md` — リサーチとプランニングに反映されるユーザーの要望 + +**グレーゾーンカテゴリ:** +| カテゴリ | 決定事項の例 | +|----------|-------------| +| ビジュアル機能 | レイアウト、密度、インタラクション、空状態 | +| API/CLI | レスポンス形式、フラグ、エラーハンドリング、詳細度 | +| コンテンツシステム | 構造、トーン、深さ、フロー | +| 構成 | グルーピング基準、命名、重複、例外 | + +--- + +### 3. UI デザインコントラクト + +**コマンド:** `/gsd-ui-phase [N]` + +**目的:** プランニング前にデザインの決定事項を確定し、フェーズ内のすべてのコンポーネントが一貫したビジュアル基準を共有できるようにします。 + +**要件:** +- REQ-UI-01: システムは既存のデザインシステムの状態を検出しなければならない（shadcn の components.json、Tailwind 設定、トークン） +- REQ-UI-02: システムは未回答のデザインコントラクトの質問のみを行わなければならない +- REQ-UI-03: システムは6つの次元（コピーライティング、ビジュアル、カラー、タイポグラフィ、スペーシング、レジストリセーフティ）に対してバリデーションしなければならない +- REQ-UI-04: バリデーションが BLOCKED を返した場合、システムはリビジョンループに入らなければならない（最大2回の反復） +- REQ-UI-05: `components.json` のない React/Next.js/Vite プロジェクトに対して、システムは shadcn の初期化を提案しなければならない +- REQ-UI-06: システムはサードパーティの shadcn レジストリに対してレジストリセーフティゲートを適用しなければならない + +**生成物:** `{padded_phase}-UI-SPEC.md` — エグゼキューターが参照するデザインコントラクト + +**6つのバリデーション次元:** +1. **コピーライティング** — CTA ラベル、空状態、エラーメッセージ +2. **ビジュアル** — フォーカルポイント、視覚的階層構造、アイコンのアクセシビリティ +3. **カラー** — アクセントカラーの使用規律、60/30/10 準拠 +4. **タイポグラフィ** — フォントサイズ/ウェイトの制約遵守 +5. **スペーシング** — グリッド配置、トークンの一貫性 +6. **レジストリセーフティ** — サードパーティコンポーネントの検査要件 + +**shadcn 連携:** +- React/Next.js/Vite プロジェクトで `components.json` が欠落していることを検出 +- ユーザーを `ui.shadcn.com/create` のプリセット設定にガイド +- プリセット文字列はフェーズ間で再現可能なプランニング成果物になる +- セーフティゲートにより、サードパーティコンポーネント使用前に `npx shadcn view` と `npx shadcn diff` が必要 + +--- + +### 4. フェーズプランニング + +**コマンド:** `/gsd-plan-phase [N] [--auto] [--skip-research] [--skip-verify]` + +**目的:** 実装ドメインをリサーチし、検証済みのアトミックな実行プランを作成します。 + +**要件:** +- REQ-PLAN-01: システムは実装アプローチを調査するフェーズリサーチャーを起動しなければならない +- REQ-PLAN-02: システムはそれぞれ2〜3タスクのプランを作成しなければならず、各タスクは1つのコンテキストウィンドウに収まるサイズとする +- REQ-PLAN-03: システムはプランを XML で構造化しなければならない。`` 要素には `name`、`files`、`action`、`verify`、`done` フィールドを含む +- REQ-PLAN-04: システムはすべてのプランに `read_first` と `acceptance_criteria` セクションを含めなければならない +- REQ-PLAN-05: `--skip-verify` が設定されていない限り、システムはプランチェッカー検証ループ（最大3回の反復）を実行しなければならない +- REQ-PLAN-06: システムはリサーチフェーズをバイパスする `--skip-research` フラグをサポートしなければならない +- REQ-PLAN-07: フロントエンドフェーズが検出され UI-SPEC.md が存在しない場合、システムはユーザーに `/gsd-ui-phase` の実行を促さなければならない（UI セーフティゲート） +- REQ-PLAN-08: `workflow.nyquist_validation` が有効な場合、システムは Nyquist バリデーションマッピングを含めなければならない +- REQ-PLAN-09: プランニング完了前に、すべてのフェーズ要件が少なくとも1つのプランでカバーされていることをシステムは検証しなければならない（要件カバレッジゲート） + +**生成物:** +| 成果物 | 説明 | +|--------|------| +| `{phase}-RESEARCH.md` | エコシステムリサーチの結果 | +| `{phase}-{N}-PLAN.md` | アトミックな実行プラン（各2〜3タスク） | +| `{phase}-VALIDATION.md` | テストカバレッジマッピング（Nyquist レイヤー） | + +**プラン構造（XML）:** +```xml + + Create login endpoint + src/app/api/auth/login/route.ts + + Use jose for JWT. Validate credentials against users table. + Return httpOnly cookie on success. + + curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie + Valid credentials return cookie, invalid return 401 + +``` + +**プランチェッカー検証（8つの次元）:** +1. 要件カバレッジ — プランがすべてのフェーズ要件に対応しているか +2. タスクのアトミック性 — 各タスクが独立してコミット可能か +3. 依存関係の順序 — タスクが正しい順序で並んでいるか +4. ファイルスコープ — プラン間で過度なファイルの重複がないか +5. 検証コマンド — 各タスクにテスト可能な完了基準があるか +6. コンテキストフィット — タスクが1つのコンテキストウィンドウに収まるか +7. ギャップ検出 — 実装ステップに欠落がないか +8. Nyquist 準拠 — タスクに自動化された検証コマンドがあるか（有効時） + +--- + +### 5. フェーズ実行 + +**コマンド:** `/gsd-execute-phase ` + +**目的:** ウェーブベースの並列化を使用して、フェーズ内のすべてのプランを実行します。各エグゼキューターにはフレッシュなコンテキストウィンドウが割り当てられます。 + +**要件:** +- REQ-EXEC-01: システムはプランの依存関係を分析し、実行ウェーブにグループ化しなければならない +- REQ-EXEC-02: システムは各ウェーブ内で独立したプランを並列実行しなければならない +- REQ-EXEC-03: システムは各エグゼキューターにフレッシュなコンテキストウィンドウ（200K トークン）を付与しなければならない +- REQ-EXEC-04: システムはタスクごとにアトミックな git コミットを生成しなければならない +- REQ-EXEC-05: システムは完了した各プランに対して SUMMARY.md を生成しなければならない +- REQ-EXEC-06: システムはフェーズ目標が達成されたかを確認する実行後検証を実行しなければならない +- REQ-EXEC-07: システムは git ブランチ戦略（`none`、`phase`、`milestone`）をサポートしなければならない +- REQ-EXEC-08: タスク検証失敗時、システムはノードリペアオペレーターを呼び出さなければならない（有効時） +- REQ-EXEC-09: システムはクロスフェーズ回帰を検出するため、検証前に過去のフェーズのテストスイートを実行しなければならない + +**生成物:** +| 成果物 | 説明 | +|--------|------| +| `{phase}-{N}-SUMMARY.md` | プランごとの実行結果 | +| `{phase}-VERIFICATION.md` | 実行後検証レポート | +| Git コミット | タスクごとのアトミックなコミット | + +**ウェーブ実行:** +- 依存関係のないプラン → ウェーブ 1（並列） +- ウェーブ 1 に依存するプラン → ウェーブ 2（並列、ウェーブ 1 完了を待機） +- すべてのプランが完了するまで継続 +- ファイル競合がある場合、同一ウェーブ内で順次実行を強制 + +**エグゼキューターの機能:** +- 完全なタスク指示を含む PLAN.md を読み取り +- PROJECT.md、STATE.md、CONTEXT.md、RESEARCH.md にアクセス可能 +- 構造化されたコミットメッセージで各タスクをアトミックにコミット +- 並列実行中のビルドロック競合を回避するため、コミット時に `--no-verify` を使用 +- チェックポイントタイプに対応: `auto`、`checkpoint:human-verify`、`checkpoint:decision`、`checkpoint:human-action` +- プランからの逸脱を SUMMARY.md に報告 + +**並列安全性:** +- **pre-commit フック**: 並列エージェントではスキップ（`--no-verify`）、各ウェーブ後にオーケストレーターが一度実行 +- **STATE.md ロック**: ファイルレベルのロックファイルにより、エージェント間の同時書き込みによるデータ破損を防止 + +--- + +### 6. 作業検証 + +**コマンド:** `/gsd-verify-work [N]` + +**目的:** ユーザー受け入れテスト — 各成果物のテストをユーザーに順に案内し、失敗を自動診断します。 + +**要件:** +- REQ-VERIFY-01: システムはフェーズからテスト可能な成果物を抽出しなければならない +- REQ-VERIFY-02: システムは成果物をユーザー確認のために1つずつ提示しなければならない +- REQ-VERIFY-03: システムは失敗を自動診断するためにデバッグエージェントを起動しなければならない +- REQ-VERIFY-04: システムは特定された問題に対する修正プランを作成しなければならない +- REQ-VERIFY-05: サーバー/データベース/シード/スタートアップファイルを変更するフェーズに対して、システムはコールドスタートスモークテストを注入しなければならない +- REQ-VERIFY-06: システムは合否結果を含む UAT.md を生成しなければならない + +**生成物:** `{phase}-UAT.md` — ユーザー受け入れテスト結果、問題が見つかった場合は修正プランも含む + +--- + +### 6.5. Ship + +**コマンド:** `/gsd-ship [N] [--draft]` + +**目的:** ローカル完了からマージ済み PR への橋渡し。検証通過後、ブランチをプッシュし、プランニング成果物から自動生成された本文で PR を作成します。オプションでレビューをトリガーし、STATE.md で追跡します。 + +**要件:** +- REQ-SHIP-01: システムはシッピング前にフェーズが検証を通過していることを確認しなければならない +- REQ-SHIP-02: システムは `gh` CLI を使用してブランチをプッシュし PR を作成しなければならない +- REQ-SHIP-03: システムは SUMMARY.md、VERIFICATION.md、REQUIREMENTS.md から PR 本文を自動生成しなければならない +- REQ-SHIP-04: システムは STATE.md をシッピングステータスと PR 番号で更新しなければならない +- REQ-SHIP-05: システムはドラフト PR のための `--draft` フラグをサポートしなければならない + +**前提条件:** フェーズ検証済み、`gh` CLI がインストール・認証済み、フィーチャーブランチで作業中 + +**生成物:** リッチな本文を持つ GitHub PR、STATE.md の更新 + +--- + +### 7. UI レビュー + +**コマンド:** `/gsd-ui-review [N]` + +**目的:** 実装済みフロントエンドコードに対する遡及的な6本柱のビジュアル監査。任意のプロジェクトでスタンドアロンで動作します。 + +**要件:** +- REQ-UIREVIEW-01: システムは6つの柱それぞれを1〜4のスケールで評価しなければならない +- REQ-UIREVIEW-02: システムは Playwright CLI を使用して `.planning/ui-reviews/` にスクリーンショットをキャプチャしなければならない +- REQ-UIREVIEW-03: システムはスクリーンショットディレクトリ用の `.gitignore` を作成しなければならない +- REQ-UIREVIEW-04: システムは優先度の高い修正トップ3を特定しなければならない +- REQ-UIREVIEW-05: システムは（UI-SPEC.md なしで）抽象的な品質基準を使用してスタンドアロンで動作しなければならない + +**6つの監査柱（1〜4で評価）:** +1. **コピーライティング** — CTA ラベル、空状態、エラー状態 +2. **ビジュアル** — フォーカルポイント、視覚的階層構造、アイコンのアクセシビリティ +3. **カラー** — アクセントカラーの使用規律、60/30/10 準拠 +4. **タイポグラフィ** — フォントサイズ/ウェイトの制約遵守 +5. **スペーシング** — グリッド配置、トークンの一貫性 +6. **エクスペリエンスデザイン** — ローディング/エラー/空状態のカバレッジ + +**生成物:** `{padded_phase}-UI-REVIEW.md` — スコアと優先度付き修正リスト + +--- + +### 8. マイルストーン管理 + +**コマンド:** `/gsd-audit-milestone`、`/gsd-complete-milestone`、`/gsd-new-milestone [name]` + +**目的:** マイルストーンの完了を検証し、アーカイブし、リリースにタグを付け、次の開発サイクルを開始します。 + +**要件:** +- REQ-MILE-01: 監査はすべてのマイルストーン要件が満たされていることを検証しなければならない +- REQ-MILE-02: 監査はスタブ、プレースホルダー実装、未テストコードを検出しなければならない +- REQ-MILE-03: 監査はフェーズ間の Nyquist バリデーション準拠をチェックしなければならない +- REQ-MILE-04: 完了時にマイルストーンデータを MILESTONES.md にアーカイブしなければならない +- REQ-MILE-05: 完了時にリリース用の git タグ作成を提案しなければならない +- REQ-MILE-06: 完了時にブランチ戦略に応じてスカッシュマージまたは履歴付きマージを提案しなければならない +- REQ-MILE-07: 完了時に UI レビューのスクリーンショットをクリーンアップしなければならない +- REQ-MILE-08: 新しいマイルストーンは new-project と同じフロー（質問 → リサーチ → 要件 → ロードマップ）に従わなければならない +- REQ-MILE-09: 新しいマイルストーンは既存のワークフロー設定をリセットしてはならない + +**ギャップクローズ:** `/gsd-plan-milestone-gaps` は監査で特定されたギャップを埋めるためのフェーズを作成します。 + +--- + +## プランニング機能 + +### 9. フェーズ管理 + +**コマンド:** `/gsd-add-phase`、`/gsd-insert-phase [N]`、`/gsd-remove-phase [N]` + +**目的:** 開発中のロードマップの動的な変更。 + +**要件:** +- REQ-PHASE-01: 追加は現在のロードマップの末尾に新しいフェーズを追加しなければならない +- REQ-PHASE-02: 挿入は既存フェーズ間に小数番号（例: 3.1）を使用しなければならない +- REQ-PHASE-03: 削除は後続のすべてのフェーズを再番号付けしなければならない +- REQ-PHASE-04: 削除は既に実行されたフェーズの削除を防止しなければならない +- REQ-PHASE-05: すべての操作は ROADMAP.md を更新し、フェーズディレクトリを作成/削除しなければならない + +--- + +### 10. Quick モード + +**コマンド:** `/gsd-quick [--full] [--discuss] [--research]` + +**目的:** GSD の保証を維持しながら、より高速なパスでアドホックなタスクを実行します。 + +**要件:** +- REQ-QUICK-01: システムは自由形式のタスク説明を受け付けなければならない +- REQ-QUICK-02: システムはフルワークフローと同じプランナー＋エグゼキューターエージェントを使用しなければならない +- REQ-QUICK-03: システムはデフォルトでリサーチ、プランチェッカー、検証をスキップしなければならない +- REQ-QUICK-04: `--full` フラグはプランチェック（最大2回の反復）と実行後検証を有効にしなければならない +- REQ-QUICK-05: `--discuss` フラグは軽量なプランニング前ディスカッションを実行しなければならない +- REQ-QUICK-06: `--research` フラグはプランニング前にフォーカスされたリサーチエージェントを起動しなければならない +- REQ-QUICK-07: フラグは組み合わせ可能でなければならない（`--discuss --research --full`） +- REQ-QUICK-08: システムは Quick タスクを `.planning/quick/YYMMDD-xxx-slug/` で追跡しなければならない +- REQ-QUICK-09: システムは Quick タスク実行時にアトミックなコミットを生成しなければならない + +--- + +### 11. 自律モード + +**コマンド:** `/gsd-autonomous [--from N]` + +**目的:** 残りのすべてのフェーズを自律的に実行します — フェーズごとにディスカッション → プラン → 実行を行います。 + +**要件:** +- REQ-AUTO-01: システムはロードマップの順序で未完了のすべてのフェーズを反復処理しなければならない +- REQ-AUTO-02: システムは各フェーズに対してディスカッション → プラン → 実行を実行しなければならない +- REQ-AUTO-03: システムは明示的なユーザー判断が必要な場面（グレーゾーンの承認、ブロッカー、バリデーション）で一時停止しなければならない +- REQ-AUTO-04: システムは各フェーズ後に ROADMAP.md を再読み込みし、動的に挿入されたフェーズを検出しなければならない +- REQ-AUTO-05: `--from N` フラグは特定のフェーズ番号から開始しなければならない + +--- + +### 12. フリーフォームルーティング + +**コマンド:** `/gsd-do` + +**目的:** 自由形式のテキストを分析し、適切な GSD コマンドにルーティングします。 + +**要件:** +- REQ-DO-01: システムは自然言語入力からユーザーの意図を解析しなければならない +- REQ-DO-02: システムは意図を最も適切な GSD コマンドにマッピングしなければならない +- REQ-DO-03: システムは実行前にルーティング結果をユーザーに確認しなければならない +- REQ-DO-04: システムはプロジェクト既存 vs プロジェクト未作成のコンテキストを区別して処理しなければならない + +--- + +### 13. ノートキャプチャ + +**コマンド:** `/gsd-note` + +**目的:** ワークフローを中断することなくアイデアを記録する、摩擦ゼロのメモ機能。タイムスタンプ付きメモの追加、全メモの一覧表示、または構造化された Todo へのプロモーションが可能です。 + +**要件:** +- REQ-NOTE-01: システムは1回の write 呼び出しでタイムスタンプ付きメモファイルを保存しなければならない +- REQ-NOTE-02: システムはプロジェクトスコープとグローバルスコープからすべてのメモを表示する `list` サブコマンドをサポートしなければならない +- REQ-NOTE-03: システムはメモを構造化された Todo に変換する `promote N` サブコマンドをサポートしなければならない +- REQ-NOTE-04: システムはグローバルスコープ操作のための `--global` フラグをサポートしなければならない +- REQ-NOTE-05: システムは task、question、bash を使用してはならない — インラインでのみ実行 + +--- + +### 14. 自動進行（Next） + +**コマンド:** `/gsd-next` + +**目的:** 現在のプロジェクト状態を自動検出し、次の論理的なワークフローステップに進めます。どのフェーズ/ステップにいるかを覚えておく必要がなくなります。 + +**要件:** +- REQ-NEXT-01: システムは STATE.md、ROADMAP.md、フェーズディレクトリを読み取り、現在のポジションを判定しなければならない +- REQ-NEXT-02: システムはディスカッション、プラン、実行、検証のいずれが必要かを検出しなければならない +- REQ-NEXT-03: システムは適切なコマンドを自動的に呼び出さなければならない +- REQ-NEXT-04: プロジェクトが存在しない場合、システムは `/gsd-new-project` を提案しなければならない +- REQ-NEXT-05: すべてのフェーズが完了している場合、システムは `/gsd-complete-milestone` を提案しなければならない + +**状態検出ロジック:** +| 状態 | アクション | +|------|----------| +| `.planning/` ディレクトリなし | `/gsd-new-project` を提案 | +| フェーズに CONTEXT.md がない | `/gsd-discuss-phase` を実行 | +| フェーズに PLAN.md ファイルがない | `/gsd-plan-phase` を実行 | +| プランはあるが SUMMARY.md がない | `/gsd-execute-phase` を実行 | +| 実行済みだが VERIFICATION.md がない | `/gsd-verify-work` を実行 | +| すべてのフェーズが完了 | `/gsd-complete-milestone` を提案 | + +--- + +## 品質保証機能 + +### 15. Nyquist バリデーション + +**目的:** コード記述前に、フェーズ要件に対する自動テストカバレッジをマッピングします。Nyquist サンプリング定理にちなんで命名 — すべての要件に対してフィードバック信号が存在することを保証します。 + +**要件:** +- REQ-NYQ-01: システムは plan-phase リサーチ中に既存のテストインフラを検出しなければならない +- REQ-NYQ-02: システムは各要件を特定のテストコマンドにマッピングしなければならない +- REQ-NYQ-03: システムはウェーブ 0 タスク（実装前に必要なテストスキャフォールディング）を特定しなければならない +- REQ-NYQ-04: プランチェッカーは Nyquist 準拠を8番目の検証次元として適用しなければならない +- REQ-NYQ-05: システムは `/gsd-validate-phase` による遡及的バリデーションをサポートしなければならない +- REQ-NYQ-06: システムは `workflow.nyquist_validation: false` で無効化可能でなければならない + +**生成物:** `{phase}-VALIDATION.md` — テストカバレッジコントラクト + +**遡及的バリデーション（`/gsd-validate-phase [N]`）:** +- 実装をスキャンし、要件をテストにマッピング +- 自動検証がない要件のギャップを特定 +- テストを生成するオーディターを起動（最大3回試行） +- 実装コードは決して変更しない — テストファイルと VALIDATION.md のみ +- 実装バグはユーザーが対処すべきエスカレーションとしてフラグ付け + +--- + +### 16. プランチェック + +**目的:** プランがフェーズ目標を達成するかを、実行前にゴールバックワード方式で検証します。 + +**要件:** +- REQ-PLANCK-01: システムは8つの品質次元に対してプランを検証しなければならない +- REQ-PLANCK-02: システムはプランが合格するまで最大3回の反復をループしなければならない +- REQ-PLANCK-03: システムは失敗に対して具体的かつ実行可能なフィードバックを提供しなければならない +- REQ-PLANCK-04: システムは `workflow.plan_check: false` で無効化可能でなければならない + +--- + +### 17. 実行後検証 + +**目的:** コードベースがフェーズの約束を達成しているかを自動チェックします。 + +**要件:** +- REQ-POSTVER-01: システムはタスク完了だけでなく、フェーズ目標に対してチェックしなければならない +- REQ-POSTVER-02: システムは合否分析を含む VERIFICATION.md を生成しなければならない +- REQ-POSTVER-03: システムは `/gsd-verify-work` が対処すべき問題をログに記録しなければならない +- REQ-POSTVER-04: システムは `workflow.verifier: false` で無効化可能でなければならない + +--- + +### 18. ノードリペア + +**目的:** 実行中にタスク検証が失敗した場合の自律的な回復。 + +**要件:** +- REQ-REPAIR-01: システムは失敗を分析し、RETRY、DECOMPOSE、PRUNE のいずれかの戦略を選択しなければならない +- REQ-REPAIR-02: RETRY は具体的な調整を加えて再試行しなければならない +- REQ-REPAIR-03: DECOMPOSE はタスクをより小さな検証可能なサブステップに分解しなければならない +- REQ-REPAIR-04: PRUNE は達成不可能なタスクを削除し、ユーザーにエスカレーションしなければならない +- REQ-REPAIR-05: システムはリペア予算を尊重しなければならない（デフォルト: タスクあたり2回の試行） +- REQ-REPAIR-06: システムは `workflow.node_repair_budget` と `workflow.node_repair` で設定可能でなければならない + +--- + +### 19. ヘルスバリデーション + +**コマンド:** `/gsd-health [--repair]` + +**目的:** `.planning/` ディレクトリの整合性を検証し、問題を自動修復します。 + +**要件:** +- REQ-HEALTH-01: システムは必須ファイルの欠落をチェックしなければならない +- REQ-HEALTH-02: システムは設定の一貫性を検証しなければならない +- REQ-HEALTH-03: システムはサマリーのない孤立したプランを検出しなければならない +- REQ-HEALTH-04: システムはフェーズ番号とロードマップの同期をチェックしなければならない +- REQ-HEALTH-05: `--repair` フラグは回復可能な問題を自動修正しなければならない + +--- + +### 20. クロスフェーズ回帰ゲート + +**目的:** 実行後に過去のフェーズのテストスイートを実行することで、フェーズ間での回帰の蓄積を防止します。 + +**要件:** +- REQ-REGR-01: システムはフェーズ実行後に、完了済みの過去のすべてのフェーズのテストスイートを実行しなければならない +- REQ-REGR-02: システムはテスト失敗をクロスフェーズ回帰として報告しなければならない +- REQ-REGR-03: 回帰は実行後検証の前に表面化されなければならない +- REQ-REGR-04: システムはどの過去フェーズのテストが壊れたかを特定しなければならない + +**実行タイミング:** `/gsd-execute-phase` の検証ステップの前に自動実行されます。 + +--- + +### 21. 要件カバレッジゲート + +**目的:** プランニング完了前に、すべてのフェーズ要件が少なくとも1つのプランでカバーされていることを保証します。 + +**要件:** +- REQ-COVGATE-01: システムは ROADMAP.md からフェーズに割り当てられたすべての要件 ID を抽出しなければならない +- REQ-COVGATE-02: システムは各要件が少なくとも1つの PLAN.md に含まれていることを検証しなければならない +- REQ-COVGATE-03: カバーされていない要件はプランニング完了をブロックしなければならない +- REQ-COVGATE-04: システムはどの特定の要件にプランカバレッジがないかを報告しなければならない + +**実行タイミング:** `/gsd-plan-phase` の末尾、プランチェッカーループの後に自動実行されます。 + +--- + +## コンテキストエンジニアリング機能 + +### 22. コンテキストウィンドウ監視 + +**目的:** コンテキストが不足し始めた際にユーザーとエージェントの両方にアラートを出し、コンテキストの劣化を防止します。 + +**要件:** +- REQ-CTX-01: ステータスラインはユーザーにコンテキスト使用率をパーセンテージで表示しなければならない +- REQ-CTX-02: コンテキストモニターは残量 35% 以下で（WARNING）エージェント向け警告を注入しなければならない +- REQ-CTX-03: コンテキストモニターは残量 25% 以下で（CRITICAL）エージェント向け警告を注入しなければならない +- REQ-CTX-04: 警告はデバウンスされなければならない（繰り返し警告間に5回のツール使用） +- REQ-CTX-05: 重大度のエスカレーション（WARNING→CRITICAL）はデバウンスをバイパスしなければならない +- REQ-CTX-06: コンテキストモニターは GSD アクティブ vs 非 GSD アクティブプロジェクトを区別しなければならない +- REQ-CTX-07: 警告はアドバイザリーであり、ユーザーの意向を上書きする命令的なコマンドであってはならない +- REQ-CTX-08: すべてのフックはサイレントに失敗し、ツール実行をブロックしてはならない + +**アーキテクチャ:** 2部構成のブリッジシステム: +1. ステータスラインがメトリクスを `/tmp/OpenCode-ctx-{session}.json` に書き込み +2. コンテキストモニターがメトリクスを読み取り、`additionalContext` 警告を注入 + +--- + +### 23. セッション管理 + +**コマンド:** `/gsd-pause-work`、`/gsd-resume-work`、`/gsd-progress` + +**目的:** コンテキストリセットやセッション間でのプロジェクトの継続性を維持します。 + +**要件:** +- REQ-SESSION-01: 一時停止は現在のポジションと次のステップを `continue-here.md` と構造化された `HANDOFF.json` に保存しなければならない +- REQ-SESSION-02: 再開は HANDOFF.json（優先）または状態ファイル（フォールバック）から完全なプロジェクトコンテキストを復元しなければならない +- REQ-SESSION-03: 進捗は現在のポジション、次のアクション、全体の完了状況を表示しなければならない +- REQ-SESSION-04: 進捗はすべての状態ファイル（STATE.md、ROADMAP.md、フェーズディレクトリ）を読み取らなければならない +- REQ-SESSION-05: すべてのセッション操作は `/new`（コンテキストリセット）後も動作しなければならない +- REQ-SESSION-06: HANDOFF.json にはブロッカー、保留中の人的アクション、進行中のタスク状態を含めなければならない +- REQ-SESSION-07: 再開時にセッション開始直後に人的アクションとブロッカーを即座に表面化しなければならない + +--- + +### 24. セッションレポート + +**コマンド:** `/gsd-session-report` + +**目的:** 実施した作業、達成した成果、推定リソース使用量をキャプチャした、構造化されたセッション後のサマリードキュメントを生成します。 + +**要件:** +- REQ-REPORT-01: システムは STATE.md、git log、プラン/サマリーファイルからデータを収集しなければならない +- REQ-REPORT-02: システムは行ったコミット、実行したプラン、進行したフェーズを含めなければならない +- REQ-REPORT-03: システムはセッションアクティビティに基づいてトークン使用量とコストを推定しなければならない +- REQ-REPORT-04: システムはアクティブなブロッカーと行った決定事項を含めなければならない +- REQ-REPORT-05: システムは次のステップを推奨しなければならない + +**生成物:** `.planning/reports/SESSION_REPORT.md` + +**レポートセクション:** +- セッション概要（期間、マイルストーン、フェーズ） +- 実施した作業（コミット、プラン、フェーズ） +- 成果と成果物 +- ブロッカーと決定事項 +- リソース推定（トークン、コスト） +- 次のステップの推奨 + +--- + +### 25. マルチエージェントオーケストレーション + +**目的:** 各タスクにフレッシュなコンテキストウィンドウを持つ専門エージェントを調整します。 + +**要件:** +- REQ-ORCH-01: 各エージェントはフレッシュなコンテキストウィンドウを受け取らなければならない +- REQ-ORCH-02: オーケストレーターは軽量でなければならない — エージェントを起動し、結果を収集し、次にルーティング +- REQ-ORCH-03: コンテキストペイロードには関連するすべてのプロジェクト成果物を含めなければならない +- REQ-ORCH-04: 並列エージェントは真に独立でなければならない（共有可変状態なし） +- REQ-ORCH-05: エージェントの結果はオーケストレーターが処理する前にディスクに書き込まれなければならない +- REQ-ORCH-06: 失敗したエージェントは検出されなければならない（実際の出力 vs 報告された失敗をスポットチェック） + +--- + +### 26. モデルプロファイル + +**コマンド:** `/gsd-set-profile ` + +**目的:** 各エージェントが使用する AI モデルを制御し、品質とコストのバランスを取ります。 + +**要件:** +- REQ-MODEL-01: システムは4つのプロファイルをサポートしなければならない: `quality`、`balanced`、`budget`、`inherit` +- REQ-MODEL-02: 各プロファイルはエージェントごとのモデルティアを定義しなければならない（プロファイルテーブル参照） +- REQ-MODEL-03: エージェントごとのオーバーライドはプロファイルより優先されなければならない +- REQ-MODEL-04: `inherit` プロファイルはランタイムの現在のモデル選択に従わなければならない +- REQ-MODEL-04a: 非 Anthropic プロバイダー（OpenRouter、ローカルモデル）を使用する場合、予期しない API コストを避けるために `inherit` プロファイルを使用しなければならない +- REQ-MODEL-05: プロファイル切り替えはプログラマティックでなければならない（スクリプト、LLM 駆動ではない） +- REQ-MODEL-06: モデル解決はオーケストレーションごとに1回のみ実行し、スポーンごとに実行してはならない + +**プロファイル割り当て:** + +| エージェント | `quality` | `balanced` | `budget` | `inherit` | +|-------------|-----------|------------|----------|-----------| +| gsd-planner | Opus | Opus | Sonnet | Inherit | +| gsd-roadmapper | Opus | Sonnet | Sonnet | Inherit | +| gsd-executor | Opus | Sonnet | Sonnet | Inherit | +| gsd-phase-researcher | Opus | Sonnet | Haiku | Inherit | +| gsd-project-researcher | Opus | Sonnet | Haiku | Inherit | +| gsd-research-synthesizer | Sonnet | Sonnet | Haiku | Inherit | +| gsd-debugger | Opus | Sonnet | Sonnet | Inherit | +| gsd-codebase-mapper | Sonnet | Haiku | Haiku | Inherit | +| gsd-verifier | Sonnet | Sonnet | Haiku | Inherit | +| gsd-plan-checker | Sonnet | Sonnet | Haiku | Inherit | +| gsd-integration-checker | Sonnet | Sonnet | Haiku | Inherit | +| gsd-nyquist-auditor | Sonnet | Sonnet | Haiku | Inherit | + +--- + +## ブラウンフィールド機能 + +### 27. コードベースマッピング + +**コマンド:** `/gsd-map-codebase [area]` + +**目的:** 新しいプロジェクトを開始する前に既存のコードベースを分析し、GSD が既存の構成を理解できるようにします。 + +**要件:** +- REQ-MAP-01: システムは各分析領域に対して並列マッパーエージェントを起動しなければならない +- REQ-MAP-02: システムは `.planning/codebase/` に構造化されたドキュメントを生成しなければならない +- REQ-MAP-03: システムは技術スタック、アーキテクチャパターン、コーディング規約、懸念事項を検出しなければならない +- REQ-MAP-04: 後続の `/gsd-new-project` はコードベースマッピングを読み込み、追加する内容に焦点を当てた質問を行わなければならない +- REQ-MAP-05: オプションの `[area]` 引数はマッピングを特定の領域にスコープしなければならない + +**生成物:** +| ドキュメント | 内容 | +|-------------|------| +| `STACK.md` | 言語、フレームワーク、データベース、インフラストラクチャ | +| `ARCHITECTURE.md` | パターン、レイヤー、データフロー、境界 | +| `CONVENTIONS.md` | 命名、ファイル構成、コードスタイル、テストパターン | +| `CONCERNS.md` | 技術的負債、セキュリティ問題、パフォーマンスボトルネック | +| `STRUCTURE.md` | ディレクトリレイアウトとファイル構成 | +| `TESTING.md` | テストインフラ、カバレッジ、パターン | +| `INTEGRATIONS.md` | 外部サービス、API、サードパーティ依存関係 | + +--- + +## ユーティリティ機能 + +### 28. デバッグシステム + +**コマンド:** `/gsd-debug [description]` + +**目的:** コンテキストリセットを超えて持続する状態を持つ、体系的なデバッグ。 + +**要件:** +- REQ-DEBUG-01: システムは `.planning/debug/` にデバッグセッションファイルを作成しなければならない +- REQ-DEBUG-02: システムは仮説、証拠、排除された理論を追跡しなければならない +- REQ-DEBUG-03: システムはコンテキストリセット後もデバッグが継続するよう状態を永続化しなければならない +- REQ-DEBUG-04: システムは解決済みとマークする前に人的検証を要求しなければならない +- REQ-DEBUG-05: 解決済みセッションは `.planning/debug/knowledge-base.md` に追記されなければならない +- REQ-DEBUG-06: ナレッジベースは再調査を防止するために新しいデバッグセッション時に参照されなければならない + +**デバッグセッションの状態:** `gathering` → `investigating` → `fixing` → `verifying` → `awaiting_human_verify` → `resolved` + +--- + +### 29. Todo 管理 + +**コマンド:** `/gsd-add-todo [desc]`、`/gsd-check-todos` + +**目的:** セッション中にアイデアやタスクをキャプチャし、後で作業できるようにします。 + +**要件:** +- REQ-TODO-01: システムは現在の会話コンテキストから Todo をキャプチャしなければならない +- REQ-TODO-02: Todo は `.planning/todos/pending/` に保存されなければならない +- REQ-TODO-03: 完了した Todo は `.planning/todos/done/` に移動されなければならない +- REQ-TODO-04: check-todos は保留中のすべてのアイテムを一覧表示し、作業するアイテムを選択できなければならない + +--- + +### 30. 統計ダッシュボード + +**コマンド:** `/gsd-stats` + +**目的:** プロジェクトメトリクスを表示します — フェーズ、プラン、要件、git 履歴、タイムライン。 + +**要件:** +- REQ-STATS-01: システムはフェーズ/プランの完了数を表示しなければならない +- REQ-STATS-02: システムは要件カバレッジを表示しなければならない +- REQ-STATS-03: システムは git コミットメトリクスを表示しなければならない +- REQ-STATS-04: システムは複数の出力形式（json、table、bar）をサポートしなければならない + +--- + +### 31. アップデートシステム + +**コマンド:** `/gsd-update` + +**目的:** GSD を最新バージョンに更新し、チェンジログのプレビューを表示します。 + +**要件:** +- REQ-UPDATE-01: システムは npm 経由で新しいバージョンをチェックしなければならない +- REQ-UPDATE-02: システムは更新前に新しいバージョンのチェンジログを表示しなければならない +- REQ-UPDATE-03: システムはランタイムを認識し、正しいディレクトリを対象としなければならない +- REQ-UPDATE-04: システムはローカルで変更されたファイルを `gsd-local-patches/` にバックアップしなければならない +- REQ-UPDATE-05: `/gsd-reapply-patches` は更新後にローカルの変更を復元しなければならない + +--- + +### 32. 設定管理 + +**コマンド:** `/gsd-settings` + +**目的:** ワークフロートグルとモデルプロファイルのインタラクティブな設定。 + +**要件:** +- REQ-SETTINGS-01: システムは現在の設定をトグルオプション付きで表示しなければならない +- REQ-SETTINGS-02: システムは `.planning/config.json` を更新しなければならない +- REQ-SETTINGS-03: システムはグローバルデフォルト（`~/.gsd/defaults.json`）としての保存をサポートしなければならない + +**設定可能な項目:** +| 設定 | 型 | デフォルト | 説明 | +|------|-----|----------|------| +| `mode` | enum | `interactive` | `interactive` または `yolo`（自動承認） | +| `granularity` | enum | `standard` | `coarse`、`standard`、または `fine` | +| `model_profile` | enum | `balanced` | `quality`、`balanced`、`budget`、または `inherit` | +| `workflow.research` | boolean | `true` | プランニング前のドメインリサーチ | +| `workflow.plan_check` | boolean | `true` | プラン検証ループ | +| `workflow.verifier` | boolean | `true` | 実行後検証 | +| `workflow.auto_advance` | boolean | `false` | ディスカッション→プラン→実行の自動チェーン | +| `workflow.nyquist_validation` | boolean | `true` | Nyquist テストカバレッジマッピング | +| `workflow.ui_phase` | boolean | `true` | UI デザインコントラクト生成 | +| `workflow.ui_safety_gate` | boolean | `true` | フロントエンドフェーズで ui-phase を促す | +| `workflow.node_repair` | boolean | `true` | 自律的なタスクリペア | +| `workflow.node_repair_budget` | number | `2` | タスクあたりの最大リペア試行回数 | +| `planning.commit_docs` | boolean | `true` | `.planning/` ファイルを git にコミット | +| `planning.search_gitignored` | boolean | `false` | gitignore されたファイルを検索に含める | +| `parallelization.enabled` | boolean | `true` | 独立したプランを同時実行 | +| `git.branching_strategy` | enum | `none` | `none`、`phase`、または `milestone` | + +--- + +### 33. テスト生成 + +**コマンド:** `/gsd-add-tests [N]` + +**目的:** 完了したフェーズに対して、UAT 基準と実装に基づいてテストを生成します。 + +**要件:** +- REQ-TEST-01: システムは完了したフェーズの実装を分析しなければならない +- REQ-TEST-02: システムは UAT 基準と受け入れ基準に基づいてテストを生成しなければならない +- REQ-TEST-03: システムは既存のテストインフラパターンを使用しなければならない + +--- + +## インフラストラクチャ機能 + +### 34. Git 連携 + +**目的:** アトミックなコミット、ブランチ戦略、クリーンな履歴管理。 + +**要件:** +- REQ-GIT-01: 各タスクは独自のアトミックなコミットを持たなければならない +- REQ-GIT-02: コミットメッセージは構造化されたフォーマットに従わなければならない: `type(scope): description` +- REQ-GIT-03: システムは3つのブランチ戦略をサポートしなければならない: `none`、`phase`、`milestone` +- REQ-GIT-04: phase 戦略はフェーズごとに1つのブランチを作成しなければならない +- REQ-GIT-05: milestone 戦略はマイルストーンごとに1つのブランチを作成しなければならない +- REQ-GIT-06: complete-milestone はスカッシュマージ（推奨）または履歴付きマージを提案しなければならない +- REQ-GIT-07: システムは `.planning/` ファイルに対して `commit_docs` 設定を尊重しなければならない +- REQ-GIT-08: システムは `.gitignore` の `.planning/` を自動検出し、コミットをスキップしなければならない + +**コミットフォーマット:** +``` +type(phase-plan): description + +# Examples: +docs(08-02): complete user registration plan +feat(08-02): add email confirmation flow +fix(03-01): correct auth token expiry +``` + +--- + +### 35. CLI ツール + +**目的:** ワークフローとエージェント向けのプログラマティックユーティリティ。反復的なインライン bash パターンを置き換えます。 + +**要件:** +- REQ-CLI-01: システムは状態、設定、フェーズ、ロードマップ操作のためのアトミックなコマンドを提供しなければならない +- REQ-CLI-02: システムは各ワークフローのすべてのコンテキストを読み込む複合 `init` コマンドを提供しなければならない +- REQ-CLI-03: システムは機械可読な出力のための `--raw` フラグをサポートしなければならない +- REQ-CLI-04: システムはサンドボックス化されたサブエージェント操作のための `--cwd` フラグをサポートしなければならない +- REQ-CLI-05: すべての操作は Windows でスラッシュパスを使用しなければならない + +**コマンドカテゴリ:** State（11サブコマンド）、Phase（5）、Roadmap（3）、Verify（8）、Template（2）、Frontmatter（4）、Scaffold（4）、Init（12）、Validate（2）、Progress、Stats、Todo + +--- + +### 36. マルチランタイムサポート + +**目的:** 6つの異なる AI コーディングエージェントランタイムで GSD を実行します。 + +**要件:** +- REQ-RUNTIME-01: システムは OpenCode、OpenCode、Gemini CLI、Codex、Copilot、Antigravity をサポートしなければならない +- REQ-RUNTIME-02: インストーラーはランタイムごとにコンテンツを変換しなければならない（ツール名、パス、フロントマター） +- REQ-RUNTIME-03: インストーラーはインタラクティブおよび非インタラクティブ（`--OpenCode --global`）モードをサポートしなければならない +- REQ-RUNTIME-04: インストーラーはグローバルとローカルの両方のインストールをサポートしなければならない +- REQ-RUNTIME-05: アンインストールは他の設定に影響を与えることなく、すべての GSD ファイルをクリーンに削除しなければならない +- REQ-RUNTIME-06: インストーラーはプラットフォームの違い（Windows、macOS、Linux、WSL、Docker）を処理しなければならない + +**ランタイム変換:** + +| 側面 | OpenCode | OpenCode | Gemini | Codex | Copilot | Antigravity | +|------|------------|----------|--------|-------|---------|-------------| +| コマンド | スラッシュコマンド | スラッシュコマンド | スラッシュコマンド | スキル（TOML） | スラッシュコマンド | スキル | +| エージェント形式 | OpenCode ネイティブ | `mode: subagent` | OpenCode ネイティブ | スキル | ツールマッピング | スキル | +| フックイベント | `PostToolUse` | N/A | `AfterTool` | N/A | N/A | N/A | +| 設定 | `settings.json` | `opencode.json(c)` | `settings.json` | TOML | Instructions | Config | + +--- + +### 37. フックシステム + +**目的:** コンテキスト監視、ステータス表示、アップデートチェックのためのランタイムイベントフック。 + +**要件:** +- REQ-HOOK-01: ステータスラインはモデル、現在のタスク、ディレクトリ、コンテキスト使用量を表示しなければならない +- REQ-HOOK-02: コンテキストモニターは閾値レベルでエージェント向け警告を注入しなければならない +- REQ-HOOK-03: アップデートチェッカーはセッション開始時にバックグラウンドで実行されなければならない +- REQ-HOOK-04: すべてのフックは `CLAUDE_CONFIG_DIR` 環境変数を尊重しなければならない +- REQ-HOOK-05: すべてのフックは3秒の stdin タイムアウトガードを含まなければならない +- REQ-HOOK-06: すべてのフックはエラー時にサイレントに失敗しなければならない +- REQ-HOOK-07: コンテキスト使用量は autocompact バッファ（16.5% リザーブ）に対して正規化されなければならない + +**ステータスライン表示:** +``` +[⬆ /gsd-update │] model │ [current task │] directory [█████░░░░░ 50%] +``` + +カラーコーディング: 50% 未満は緑、65% 未満は黄、80% 未満はオレンジ、80% 以上はドクロ絵文字付き赤 + +### 38. 開発者プロファイリング + +**コマンド:** `/gsd-profile-user [--questionnaire] [--refresh]` + +**目的:** OpenCode のセッション履歴を分析し、8つの次元にわたる行動プロファイルを構築します。開発者のスタイルに合わせて OpenCode のレスポンスをパーソナライズするための成果物を生成します。 + +**次元:** +1. コミュニケーションスタイル（簡潔 vs 冗長、フォーマル vs カジュアル） +2. 意思決定パターン（迅速 vs 慎重、リスク許容度） +3. デバッグアプローチ（体系的 vs 直感的、ログの好み） +4. UX の好み（デザインセンス、アクセシビリティの認識） +5. ベンダー/テクノロジーの選択（フレームワークの好み、エコシステムへの精通度） +6. フラストレーションのトリガー（ワークフローで摩擦を引き起こすもの） +7. 学習スタイル（ドキュメント vs 例、深さの好み） +8. 説明の深さ（ハイレベル vs 実装詳細） + +**生成される成果物:** +- `USER-PROFILE.md` — 証拠引用付きの完全な行動プロファイル +- `/gsd-dev-preferences` コマンド — 任意のセッションで好みを読み込み +- `AGENTS.md` プロファイルセクション — OpenCode により自動検出 + +**フラグ:** +- `--questionnaire` — セッション履歴が利用できない場合のインタラクティブなアンケートフォールバック +- `--refresh` — セッションを再分析してプロファイルを再生成 + +**パイプラインモジュール:** +- `profile-pipeline.cjs` — セッションスキャン、メッセージ抽出、サンプリング +- `profile-output.cjs` — プロファイルレンダリング、アンケート、成果物生成 +- `gsd-user-profiler` エージェント — セッションデータからの行動分析 + +**要件:** +- REQ-PROF-01: セッション分析は少なくとも8つの行動次元をカバーしなければならない +- REQ-PROF-02: プロファイルは実際のセッションメッセージからの証拠を引用しなければならない +- REQ-PROF-03: セッション履歴がない場合、アンケートがフォールバックとして利用可能でなければならない +- REQ-PROF-04: 生成された成果物は OpenCode により検出可能でなければならない（AGENTS.md 連携） + +### 39. 実行ハードニング + +**目的:** 実行パイプラインに対する3つの段階的な品質改善。クロスプランの失敗が連鎖する前に検出します。 + +**コンポーネント:** + +**1. プレウェーブ依存関係チェック**（execute-phase） +ウェーブ N+1 を起動する前に、前のウェーブの成果物からのキーリンクが存在し、正しく接続されていることを検証します。クロスプランの依存関係ギャップが下流の失敗に連鎖するのを防ぎます。 + +**2. クロスプランデータコントラクト — 第9次元**（plan-checker） +データパイプラインを共有するプランが互換性のある変換を持っているかチェックする新しい分析次元。あるプランが別のプランが元の形式で必要とするデータを削除する場合にフラグを立てます。 + +**3. エクスポートレベルスポットチェック**（verify-phase） +レベル3の配線検証が通過した後、個々のエクスポートが実際に使用されているかスポットチェックします。配線されたファイル内に存在するが呼び出されないデッドストアを検出します。 + +**要件:** +- REQ-HARD-01: プレウェーブチェックは次のウェーブを起動する前に、すべての前のウェーブの成果物からのキーリンクを検証しなければならない +- REQ-HARD-02: クロスプランコントラクトチェックはプラン間の互換性のないデータ変換を検出しなければならない +- REQ-HARD-03: エクスポートスポットチェックは配線されたファイル内のデッドストアを特定しなければならない + +--- + +### 40. 検証デット追跡 + +**コマンド:** `/gsd-audit-uat` + +**目的:** 未解決のテストを持つフェーズを通過した際の UAT/検証項目のサイレントな喪失を防止します。すべての過去フェーズの検証デットを表面化し、項目が忘れられないようにします。 + +**コンポーネント:** + +**1. クロスフェーズヘルスチェック**（progress.md ステップ 1.6） +すべての `/gsd-progress` 呼び出しで、現在のマイルストーンのすべてのフェーズの未解決項目（pending、skipped、blocked、human_needed）をスキャンします。アクション可能なリンク付きのノンブロッキング警告セクションを表示します。 + +**2. `status: partial`**（verify-work.md、UAT.md） +「セッション終了」と「すべてのテスト解決済み」を区別する新しい UAT ステータス。テストがまだ pending、blocked、または理由なく skipped の場合に `status: complete` を防止します。 + +**3. `result: blocked` と `blocked_by` タグ**（verify-work.md、UAT.md） +外部依存関係（サーバー、物理デバイス、リリースビルド、サードパーティサービス）によりブロックされたテストのための新しいテスト結果タイプ。スキップされたテストとは別にカテゴリ分けされます。 + +**4. HUMAN-UAT.md の永続化**（execute-phase.md） +検証が `human_needed` を返した場合、項目は `status: partial` の追跡可能な HUMAN-UAT.md ファイルとして永続化されます。クロスフェーズヘルスチェックと監査システムに反映されます。 + +**5. フェーズ完了警告**（phase.cjs、transition.md） +`phase complete` CLI は JSON 出力に検証デット警告を返します。トランジションワークフローは確認前に未解決項目を表面化します。 + +**要件:** +- REQ-DEBT-01: システムは `/gsd-progress` ですべての過去フェーズの未解決 UAT/検証項目を表面化しなければならない +- REQ-DEBT-02: システムは不完全なテスト（partial）と完了したテスト（complete）を区別しなければならない +- REQ-DEBT-03: システムはブロックされたテストを `blocked_by` タグでカテゴリ分けしなければならない +- REQ-DEBT-04: システムは human_needed の検証項目を追跡可能な UAT ファイルとして永続化しなければならない +- REQ-DEBT-05: システムは検証デットが存在する場合、フェーズ完了とトランジション時に警告（ノンブロッキング）しなければならない +- REQ-DEBT-06: `/gsd-audit-uat` はすべてのフェーズをスキャンし、項目をテスト可能性別にカテゴリ分けし、人的テストプランを生成しなければならない + +--- + +## v1.27 の機能 + +### 41. Fast モード + +**コマンド:** `/gsd-fast [task description]` + +**目的:** サブエージェントの起動や PLAN.md ファイルの生成なしに、些細なタスクをインラインで実行します。プランニングのオーバーヘッドを正当化できないほど小さなタスク向け: タイポ修正、設定変更、小規模なリファクタリング、コミット忘れ、簡単な追加。 + +**要件:** +- REQ-FAST-01: システムはサブエージェントなしで現在のコンテキストでタスクを直接実行しなければならない +- REQ-FAST-02: システムは変更に対してアトミックな git コミットを生成しなければならない +- REQ-FAST-03: システムは状態の一貫性のためにタスクを `.planning/quick/` で追跡しなければならない +- REQ-FAST-04: リサーチ、マルチステッププランニング、または検証が必要なタスクにシステムを使用してはならない + +**`/gsd-quick` との使い分け:** +- `/gsd-fast` — 2分以内に実行可能な一文のタスク（タイポ修正、設定変更、小規模な追加） +- `/gsd-quick` — リサーチ、マルチステッププランニング、または検証が必要なもの + +--- + +### 42. クロス AI ピアレビュー + +**コマンド:** `/gsd-review --phase N [--gemini] [--OpenCode] [--codex] [--all]` + +**目的:** 外部の AI CLI（Gemini、OpenCode、Codex）を呼び出して、フェーズプランを独立してレビューします。レビュアーごとのフィードバックを含む構造化された REVIEWS.md を生成します。 + +**要件:** +- REQ-REVIEW-01: システムはシステム上で利用可能な AI CLI を検出しなければならない +- REQ-REVIEW-02: システムはフェーズプランから構造化されたレビュープロンプトを構築しなければならない +- REQ-REVIEW-03: システムは選択された各 CLI を独立して呼び出さなければならない +- REQ-REVIEW-04: システムはレスポンスを収集して `REVIEWS.md` を生成しなければならない +- REQ-REVIEW-05: レビューは `/gsd-plan-phase --reviews` で使用可能でなければならない + +**生成物:** `{phase}-REVIEWS.md` — レビュアーごとの構造化されたフィードバック + +--- + +### 43. バックログパーキングロット + +**コマンド:** `/gsd-add-backlog `、`/gsd-review-backlog`、`/gsd-plant-seed ` + +**目的:** アクティブなプランニングの準備ができていないアイデアをキャプチャします。バックログ項目は 999.x の番号付けを使用して、アクティブなフェーズシーケンスの外に留まります。シードは、適切なマイルストーンで自動的に表面化するトリガー条件を持つ、将来を見据えたアイデアです。 + +**要件:** +- REQ-BACKLOG-01: バックログ項目はアクティブなフェーズシーケンスの外に留まるために 999.x の番号付けを使用しなければならない +- REQ-BACKLOG-02: `/gsd-discuss-phase` と `/gsd-plan-phase` が動作するよう、フェーズディレクトリは即座に作成されなければならない +- REQ-BACKLOG-03: `/gsd-review-backlog` は項目ごとにプロモート、維持、削除のアクションをサポートしなければならない +- REQ-BACKLOG-04: プロモートされた項目はアクティブなマイルストーンシーケンスに再番号付けされなければならない +- REQ-SEED-01: シードは完全な WHY と表面化条件の WHEN をキャプチャしなければならない +- REQ-SEED-02: `/gsd-new-milestone` はシードをスキャンして一致するものを提示しなければならない + +**生成物:** +| 成果物 | 説明 | +|--------|------| +| `.planning/phases/999.x-slug/` | バックログ項目ディレクトリ | +| `.planning/seeds/SEED-NNN-slug.md` | トリガー条件付きシード | + +--- + +### 44. 永続コンテキストスレッド + +**コマンド:** `/gsd-thread [name | description]` + +**目的:** 複数セッションにまたがるが特定のフェーズには属さない作業のための、軽量なクロスセッションナレッジストア。`/gsd-pause-work` よりも軽量 — フェーズ状態やプランコンテキストは不要です。 + +**要件:** +- REQ-THREAD-01: システムは作成、一覧、再開モードをサポートしなければならない +- REQ-THREAD-02: スレッドは `.planning/threads/` にマークダウンファイルとして保存されなければならない +- REQ-THREAD-03: スレッドファイルには Goal、Context、References、Next Steps セクションを含めなければならない +- REQ-THREAD-04: スレッドの再開時にその完全なコンテキストを現在のセッションに読み込まなければならない +- REQ-THREAD-05: スレッドはフェーズまたはバックログ項目にプロモート可能でなければならない + +**生成物:** `.planning/threads/{slug}.md` — 永続コンテキストスレッド + +--- + +### 45. PR ブランチフィルタリング + +**コマンド:** `/gsd-pr-branch [target branch]` + +**目的:** `.planning/` のコミットを除外して、プルリクエストに適したクリーンなブランチを作成します。レビュアーにはコード変更のみが表示され、GSD プランニング成果物は表示されません。 + +**要件:** +- REQ-PRBRANCH-01: システムは `.planning/` ファイルのみを変更するコミットを特定しなければならない +- REQ-PRBRANCH-02: システムはプランニングコミットを除外した新しいブランチを作成しなければならない +- REQ-PRBRANCH-03: コード変更はコミットされた通りに正確に保持されなければならない + +--- + +### 46. セキュリティハードニング + +**目的:** GSD のプランニング成果物に対する多層防御セキュリティ。GSD は LLM のシステムプロンプトとなるマークダウンファイルを生成するため、これらのファイルに流入するユーザー制御テキストは間接的なプロンプトインジェクションの潜在的なベクターです。 + +**コンポーネント:** + +**1. 集中型セキュリティモジュール**（`security.cjs`） +- パストラバーサル防止 — ファイルパスがプロジェクトディレクトリ内に解決されることを検証 +- プロンプトインジェクション検出 — ユーザー提供テキスト内の既知のインジェクションパターンをスキャン +- 安全な JSON パース — 状態破損前に不正な入力をキャッチ +- フィールド名バリデーション — 設定フィールド名を通じたインジェクションを防止 +- シェル引数バリデーション — シェル補間前にユーザーテキストをサニタイズ + +**2. プロンプトインジェクションガードフック**（`gsd-prompt-guard.js`） +`.planning/` を対象とする write/edit 呼び出しをインジェクションパターンでスキャンする PreToolUse フック。アドバイザリーのみ — 正当な操作をブロックせず、検出を認識のためにログ記録します。 + +**3. ワークフローガードフック**（`gsd-workflow-guard.js`） +OpenCode が GSD ワークフローコンテキスト外でファイル編集を試行した際に検出する PreToolUse フック。直接編集の代わりに `/gsd-quick` や `/gsd-fast` の使用をアドバイスします。`hooks.workflow_guard`（デフォルト: false）で設定可能です。 + +**4. CI 対応インジェクションスキャナー**（`prompt-injection-scan.test.cjs`） +すべてのエージェント、ワークフロー、コマンドファイルに埋め込まれたインジェクションベクターをスキャンするテストスイート。 + +**要件:** +- REQ-SEC-01: すべてのユーザー提供ファイルパスはプロジェクトディレクトリに対して検証されなければならない +- REQ-SEC-02: プロンプトインジェクションパターンはテキストがプランニング成果物に入る前に検出されなければならない +- REQ-SEC-03: セキュリティフックはアドバイザリーのみでなければならない（正当な操作を決してブロックしない） +- REQ-SEC-04: ユーザー入力の JSON パースは不正なデータをグレースフルにキャッチしなければならない +- REQ-SEC-05: macOS の `/var` → `/private/var` シンボリックリンク解決がパスバリデーションで処理されなければならない + +--- + +### 47. マルチリポワークスペースサポート + +**目的:** モノレポおよびマルチリポ構成のための自動検出とプロジェクトルート解決。`.planning/` がリポジトリ境界を超えて解決する必要がある場合のワークスペースをサポートします。 + +**要件:** +- REQ-MULTIREPO-01: システムはマルチリポワークスペース設定を自動検出しなければならない +- REQ-MULTIREPO-02: システムはリポジトリ境界を超えてプロジェクトルートを解決しなければならない +- REQ-MULTIREPO-03: エグゼキューターはマルチリポモードでリポジトリごとのコミットハッシュを記録しなければならない + +--- + +### 48. ディスカッション監査証跡 + +**目的:** `/gsd-discuss-phase` 中に `DISCUSSION-LOG.md` を自動生成し、ディスカッション中の決定事項の完全な監査証跡を残します。 + +**要件:** +- REQ-DISCLOG-01: システムは discuss-phase 中に DISCUSSION-LOG.md を自動生成しなければならない +- REQ-DISCLOG-02: ログは質問内容、提示されたオプション、行われた決定をキャプチャしなければならない +- REQ-DISCLOG-03: 決定 ID は discuss-phase から plan-phase へのトレーサビリティを可能にしなければならない + +--- + +## v1.28 の機能 + +### 49. フォレンジクス + +**コマンド:** `/gsd-forensics [description]` + +**目的:** 失敗または停滞した GSD ワークフローのポストモーテム調査。 + +**要件:** +- REQ-FORENSICS-01: システムは git 履歴の異常（停滞ループ、長いギャップ、繰り返しコミット）を分析しなければならない +- REQ-FORENSICS-02: システムは成果物の整合性をチェックしなければならない（完了したフェーズに期待されるファイルがあるか） +- REQ-FORENSICS-03: システムは `.planning/forensics/` に保存されるマークダウンレポートを生成しなければならない +- REQ-FORENSICS-04: システムは調査結果で GitHub Issue の作成を提案しなければならない +- REQ-FORENSICS-05: システムはプロジェクトファイルを変更してはならない（読み取り専用の調査） + +**生成物:** +| 成果物 | 説明 | +|--------|------| +| `.planning/forensics/report-{timestamp}.md` | ポストモーテム調査レポート | + +**プロセス:** +1. **スキャン** — git 履歴の異常を分析: 停滞ループ、コミット間の長いギャップ、繰り返しの同一コミット +2. **整合性チェック** — 完了したフェーズに期待される成果物ファイルがあるか検証 +3. **レポート** — 調査結果を含むマークダウンレポートを生成し、`.planning/forensics/` に保存 +4. **Issue** — チームの可視性のため、調査結果で GitHub Issue の作成を提案 + +--- + +### 50. マイルストーンサマリー + +**コマンド:** `/gsd-milestone-summary [version]` + +**目的:** チームオンボーディングのためにマイルストーン成果物から包括的なプロジェクトサマリーを生成します。 + +**要件:** +- REQ-SUMMARY-01: システムはフェーズプラン、サマリー、検証結果を集約しなければならない +- REQ-SUMMARY-02: システムは現在のマイルストーンとアーカイブ済みマイルストーンの両方で動作しなければならない +- REQ-SUMMARY-03: システムは単一のナビゲート可能なドキュメントを生成しなければならない + +**生成物:** +| 成果物 | 説明 | +|--------|------| +| `MILESTONE-SUMMARY.md` | マイルストーン成果物の包括的でナビゲート可能なサマリー | + +**プロセス:** +1. **収集** — 対象マイルストーンからフェーズプラン、サマリー、検証結果を集約 +2. **統合** — 成果物をクロスリファレンス付きの単一のナビゲート可能なドキュメントに結合 +3. **出力** — チームオンボーディングとステークホルダーレビューに適した `MILESTONE-SUMMARY.md` を作成 + +--- + +### 51. ワークストリームネームスペーシング + +**コマンド:** `/gsd-workstreams` + +**目的:** 異なるマイルストーン領域での同時作業のための並列ワークストリーム。 + +**要件:** +- REQ-WS-01: システムはワークストリーム状態を個別の `.planning/workstreams/{name}/` ディレクトリに分離しなければならない +- REQ-WS-02: システムはワークストリーム名を検証しなければならない（英数字とハイフンのみ、パストラバーサルなし） +- REQ-WS-03: システムは list、create、switch、status、progress、complete、resume サブコマンドをサポートしなければならない + +**生成物:** +| 成果物 | 説明 | +|--------|------| +| `.planning/workstreams/{name}/` | 分離されたワークストリームディレクトリ構造 | + +**プロセス:** +1. **作成** — 分離された `.planning/workstreams/{name}/` ディレクトリで名前付きワークストリームを初期化 +2. **切り替え** — 後続の GSD コマンドのためにアクティブなワークストリームコンテキストを変更 +3. **管理** — ワークストリームの一覧表示、ステータス確認、進捗追跡、完了、または再開 + +--- + +### 52. マネージャーダッシュボード + +**コマンド:** `/gsd-manager` + +**目的:** 1つのターミナルから複数のフェーズを管理するためのインタラクティブなコマンドセンター。 + +**要件:** +- REQ-MGR-01: システムはすべてのフェーズの概要をステータス付きで表示しなければならない +- REQ-MGR-02: システムは現在のマイルストーンスコープにフィルタリングしなければならない +- REQ-MGR-03: システムはフェーズの依存関係と競合を表示しなければならない + +**生成物:** インタラクティブなターミナル出力 + +**プロセス:** +1. **スキャン** — 現在のマイルストーンのすべてのフェーズとそのステータスを読み込み +2. **表示** — フェーズの依存関係、競合、進捗を示す概要をレンダリング +3. **操作** — 個々のフェーズのナビゲーション、検査、操作のコマンドを受け付け + +--- + +### 53. Assumptions ディスカッションモード + +**コマンド:** `/gsd-discuss-phase`（`workflow.discuss_mode: 'assumptions'` 設定時） + +**目的:** インタビュー形式の質問をコードベースファーストの仮定分析に置き換えます。 + +**要件:** +- REQ-ASSUME-01: システムは質問の前にコードベースを分析して構造化された仮定を生成しなければならない +- REQ-ASSUME-02: システムは仮定を信頼度レベル（Confident/Likely/Unclear）で分類しなければならない +- REQ-ASSUME-03: システムはデフォルトのディスカスモードと同一の CONTEXT.md フォーマットを生成しなければならない +- REQ-ASSUME-04: システムは信頼度ベースのスキップゲートをサポートしなければならない（すべて HIGH の場合は質問なし） + +**生成物:** +| 成果物 | 説明 | +|--------|------| +| `{phase}-CONTEXT.md` | デフォルトのディスカスモードと同じフォーマット | + +**プロセス:** +1. **分析** — コードベースをスキャンして実装アプローチに関する構造化された仮定を生成 +2. **分類** — 仮定を信頼度レベル別にカテゴリ分け: Confident、Likely、Unclear +3. **ゲート** — すべての仮定が HIGH 信頼度の場合、質問を完全にスキップ +4. **確認** — 不明確な仮定をターゲット化された質問としてユーザーに提示 +5. **出力** — デフォルトのディスカスモードと同一フォーマットで `{phase}-CONTEXT.md` を生成 + +--- + +### 54. UI フェーズ自動検出 + +**対象:** `/gsd-new-project` および `/gsd-progress` + +**目的:** UI 重視のプロジェクトを自動検出し、`/gsd-ui-phase` の推奨を表面化します。 + +**要件:** +- REQ-UI-DETECT-01: システムはプロジェクト説明の UI シグナル（キーワード、フレームワーク参照）を検出しなければならない +- REQ-UI-DETECT-02: システムは該当する場合に ROADMAP.md のフェーズに `ui_hint` をアノテーションしなければならない +- REQ-UI-DETECT-03: システムは UI 重視フェーズのネクストステップに `/gsd-ui-phase` を提案しなければならない +- REQ-UI-DETECT-04: システムは `/gsd-ui-phase` を必須にしてはならない + +**プロセス:** +1. **検出** — プロジェクト説明と技術スタックの UI シグナル（キーワード、フレームワーク参照）をスキャン +2. **アノテーション** — ROADMAP.md の該当フェーズに `ui_hint` マーカーを追加 +3. **表面化** — UI 重視フェーズのネクストステップに `/gsd-ui-phase` の推奨を含める + +--- + +### 55. マルチランタイムインストーラー選択 + +**対象:** `npx gsd-opencode` + +**目的:** 1回のインタラクティブなインストールセッションで複数のランタイムを選択します。 + +**要件:** +- REQ-MULTI-RT-01: インタラクティブプロンプトはマルチセレクトをサポートしなければならない（例: OpenCode + Gemini） +- REQ-MULTI-RT-02: CLI フラグは非インタラクティブインストールで引き続き動作しなければならない + +**プロセス:** +1. **検出** — システム上で利用可能な AI CLI ランタイムを特定 +2. **プロンプト** — ランタイム選択のためのマルチセレクトインターフェースを提示 +3. **インストール** — 1回のセッションで選択されたすべてのランタイムに対して GSD を設定 diff --git a/gsd-opencode/docs/ja-JP/README.md b/gsd-opencode/docs/ja-JP/README.md new file mode 100644 index 0000000..146a8cf --- /dev/null +++ b/gsd-opencode/docs/ja-JP/README.md @@ -0,0 +1,27 @@ +# GSD ドキュメント + +Get Shit Done（GSD）フレームワークの包括的なドキュメントです。GSD は、AI コーディングエージェント向けのメタプロンプティング、コンテキストエンジニアリング、仕様駆動開発システムです。 + +## ドキュメント一覧 + +| ドキュメント | 対象読者 | 説明 | +|------------|---------|------| +| [アーキテクチャ](ARCHITECTURE.md) | コントリビューター、上級ユーザー | システムアーキテクチャ、エージェントモデル、データフロー、内部設計 | +| [機能リファレンス](FEATURES.md) | 全ユーザー | 全機能の詳細ドキュメントと要件 | +| [コマンドリファレンス](COMMANDS.md) | 全ユーザー | 全コマンドの構文、フラグ、オプション、使用例 | +| [設定リファレンス](CONFIGURATION.md) | 全ユーザー | 設定スキーマ、ワークフロートグル、モデルプロファイル、Git ブランチ | +| [CLI ツールリファレンス](CLI-TOOLS.md) | コントリビューター、エージェント作成者 | `gsd-tools.cjs` のプログラマティック API（ワークフローおよびエージェント向け） | +| [エージェントリファレンス](AGENTS.md) | コントリビューター、上級ユーザー | 全15種の専門エージェント — 役割、ツール、スポーンパターン | +| [ユーザーガイド](USER-GUIDE.md) | 全ユーザー | ワークフローのウォークスルー、トラブルシューティング、リカバリー | +| [コンテキストモニター](context-monitor.md) | 全ユーザー | コンテキストウィンドウ監視フックのアーキテクチャ | +| [ディスカスモード](workflow-discuss-mode.md) | 全ユーザー | discuss フェーズにおける assumptions モードと interview モード | + +## クイックリンク + +- **v1.28 の新機能:** フォレンジクス、マイルストーンサマリー、ワークストリーム、assumptions モード、UI 自動検出、マネージャーダッシュボード +- **はじめに:** [README](../README.md) → インストール → `/gsd-new-project` +- **ワークフロー完全ガイド:** [ユーザーガイド](USER-GUIDE.md) +- **コマンド一覧:** [コマンドリファレンス](COMMANDS.md) +- **GSD の設定:** [設定リファレンス](CONFIGURATION.md) +- **システム内部の仕組み:** [アーキテクチャ](ARCHITECTURE.md) +- **コントリビュートや拡張:** [CLI ツールリファレンス](CLI-TOOLS.md) + [エージェントリファレンス](AGENTS.md) diff --git a/gsd-opencode/docs/ja-JP/USER-GUIDE.md b/gsd-opencode/docs/ja-JP/USER-GUIDE.md new file mode 100644 index 0000000..960683f --- /dev/null +++ b/gsd-opencode/docs/ja-JP/USER-GUIDE.md @@ -0,0 +1,842 @@ +# GSD ユーザーガイド + +ワークフロー、トラブルシューティング、設定の詳細なリファレンスです。クイックスタートの設定については、[README](../README.md) をご覧ください。 + +--- + +## 目次 + +- [ワークフロー図](#ワークフロー図) +- [UI デザインコントラクト](#ui-デザインコントラクト) +- [バックログとスレッド](#バックログとスレッド) +- [ワークストリーム](#ワークストリーム) +- [セキュリティ](#セキュリティ) +- [コマンドリファレンス](#コマンドリファレンス) +- [設定リファレンス](#設定リファレンス) +- [使用例](#使用例) +- [トラブルシューティング](#トラブルシューティング) +- [リカバリークイックリファレンス](#リカバリークイックリファレンス) + +--- + +## ワークフロー図 + +### プロジェクト全体のライフサイクル + +``` + ┌──────────────────────────────────────────────────┐ + │ NEW PROJECT │ + │ /gsd-new-project │ + │ Questions -> Research -> Requirements -> Roadmap│ + └─────────────────────────┬────────────────────────┘ + │ + ┌──────────────▼─────────────┐ + │ FOR EACH PHASE: │ + │ │ + │ ┌────────────────────┐ │ + │ │ /gsd-discuss-phase │ │ <- Lock in preferences + │ └──────────┬─────────┘ │ + │ │ │ + │ ┌──────────▼─────────┐ │ + │ │ /gsd-ui-phase │ │ <- Design contract (frontend) + │ └──────────┬─────────┘ │ + │ │ │ + │ ┌──────────▼─────────┐ │ + │ │ /gsd-plan-phase │ │ <- Research + Plan + Verify + │ └──────────┬─────────┘ │ + │ │ │ + │ ┌──────────▼─────────┐ │ + │ │ /gsd-execute-phase │ │ <- Parallel execution + │ └──────────┬─────────┘ │ + │ │ │ + │ ┌──────────▼─────────┐ │ + │ │ /gsd-verify-work │ │ <- Manual UAT + │ └──────────┬─────────┘ │ + │ │ │ + │ ┌──────────▼─────────┐ │ + │ │ /gsd-ship │ │ <- Create PR (optional) + │ └──────────┬─────────┘ │ + │ │ │ + │ Next Phase?────────────┘ + │ │ No + └─────────────┼──────────────┘ + │ + ┌───────────────▼──────────────┐ + │ /gsd-audit-milestone │ + │ /gsd-complete-milestone │ + └───────────────┬──────────────┘ + │ + Another milestone? + │ │ + Yes No -> Done! + │ + ┌───────▼──────────────┐ + │ /gsd-new-milestone │ + └──────────────────────┘ +``` + +### プランニングエージェントの連携 + +``` + /gsd-plan-phase N + │ + ├── Phase Researcher (x4 parallel) + │ ├── Stack researcher + │ ├── Features researcher + │ ├── Architecture researcher + │ └── Pitfalls researcher + │ │ + │ ┌──────▼──────┐ + │ │ RESEARCH.md │ + │ └──────┬──────┘ + │ │ + │ ┌──────▼──────┐ + │ │ Planner │ <- Reads PROJECT.md, REQUIREMENTS.md, + │ │ │ CONTEXT.md, RESEARCH.md + │ └──────┬──────┘ + │ │ + │ ┌──────▼───────────┐ ┌────────┐ + │ │ Plan Checker │────>│ PASS? │ + │ └──────────────────┘ └───┬────┘ + │ │ + │ Yes │ No + │ │ │ │ + │ │ └───┘ (loop, up to 3x) + │ │ + │ ┌─────▼──────┐ + │ │ PLAN files │ + │ └────────────┘ + └── Done +``` + +### バリデーションアーキテクチャ（Nyquist レイヤー） + +plan-phase のリサーチ時に、GSD はコードが書かれる前に各フェーズ要件に対する自動テストカバレッジをマッピングします。これにより、OpenCode のエグゼキューターがタスクをコミットした際に、数秒以内で検証できるフィードバックメカニズムが既に存在することが保証されます。 + +リサーチャーは既存のテストインフラを検出し、各要件を特定のテストコマンドにマッピングし、実装開始前に作成が必要なテストスキャフォールディングを特定します（Wave 0 タスク）。 + +プランチェッカーはこれを8番目の検証次元として強制します：自動検証コマンドが不足しているタスクを含むプランは承認されません。 + +**出力：** `{phase}-VALIDATION.md` -- フェーズのフィードバックコントラクト。 + +**無効化：** テストインフラが重視されないラピッドプロトタイピングフェーズでは、`/gsd-settings` で `workflow.nyquist_validation: false` を設定してください。 + +### 遡及バリデーション (`/gsd-validate-phase`) + +Nyquist バリデーションが存在する前に実行されたフェーズ、または従来のテストスイートのみを持つ既存コードベースに対して、遡及的に監査しカバレッジのギャップを埋めます： + +``` + /gsd-validate-phase N + | + +-- Detect state (VALIDATION.md exists? SUMMARY.md exists?) + | + +-- Discover: scan implementation, map requirements to tests + | + +-- Analyze gaps: which requirements lack automated verification? + | + +-- Present gap plan for approval + | + +-- Spawn auditor: generate tests, run, debug (max 3 attempts) + | + +-- Update VALIDATION.md + | + +-- COMPLIANT -> all requirements have automated checks + +-- PARTIAL -> some gaps escalated to manual-only +``` + +オーディターは実装コードを変更しません — テストファイルと VALIDATION.md のみを変更します。テストが実装のバグを発見した場合、対処が必要なエスカレーションとしてフラグが立てられます。 + +**使用タイミング：** Nyquist が有効化される前にプランニングされたフェーズを実行した後、または `/gsd-audit-milestone` が Nyquist コンプライアンスのギャップを検出した後。 + +### 前提確認ディスカッションモード + +デフォルトでは、`/gsd-discuss-phase` は実装の好みについてオープンエンドな質問を行います。前提確認モードではこれを反転させます：GSD がまずコードベースを読み込み、フェーズの構築方法に関する構造化された前提を提示し、修正が必要な箇所のみを確認します。 + +**有効化：** `/gsd-settings` で `workflow.discuss_mode` を `'assumptions'` に設定します。 + +**動作の仕組み：** +1. PROJECT.md、コードベースマッピング、既存の規約を読み込む +2. 前提の構造化リストを生成（技術選定、パターン、ファイル配置） +3. 前提を提示し、確認・修正・補足を求める +4. 確認された前提から CONTEXT.md を作成 + +**使用タイミング：** +- コードベースを熟知している経験豊富な開発者 +- オープンエンドな質問が作業を遅らせる高速イテレーション +- パターンが確立されていて予測可能なプロジェクト + +ディスカッションモードの完全なリファレンスは [docs/workflow-discuss-mode.md](../workflow-discuss-mode.md) をご覧ください。 + +--- + +## UI デザインコントラクト + +### 背景 + +AI 生成のフロントエンドの見た目が一貫しないのは、OpenCode の UI 能力が低いからではなく、実行前にデザインコントラクトが存在しなかったためです。共通のスペーシングスケール、カラーコントラクト、コピーライティング基準なしに構築された5つのコンポーネントは、5つのわずかに異なるビジュアル上の判断を生み出します。 + +`/gsd-ui-phase` はプランニング前にデザインコントラクトを確定させます。`/gsd-ui-review` は実行後に結果を監査します。 + +### コマンド + +| コマンド | 説明 | +|---------|-------------| +| `/gsd-ui-phase [N]` | フロントエンドフェーズ用の UI-SPEC.md デザインコントラクトを生成 | +| `/gsd-ui-review [N]` | 実装済み UI の遡及的6ピラービジュアル監査 | + +### ワークフロー：`/gsd-ui-phase` + +**実行タイミング：** `/gsd-discuss-phase` の後、`/gsd-plan-phase` の前 — フロントエンド/UI 作業を含むフェーズで使用。 + +**フロー：** +1. CONTEXT.md、RESEARCH.md、REQUIREMENTS.md を読み込んで既存の決定事項を確認 +2. デザインシステムの状態を検出（shadcn components.json、Tailwind 設定、既存トークン） +3. shadcn 初期化ゲート — React/Next.js/Vite プロジェクトで未設定の場合、初期化を提案 +4. 未回答のデザインコントラクト質問のみを確認（スペーシング、タイポグラフィ、カラー、コピーライティング、レジストリの安全性） +5. `{phase}-UI-SPEC.md` をフェーズディレクトリに書き出す +6. 6つの次元で検証（コピーライティング、ビジュアル、カラー、タイポグラフィ、スペーシング、レジストリの安全性） +7. BLOCKED の場合はリビジョンループ（最大2回） + +**出力：** `.planning/phases/{phase-dir}/` 内の `{padded_phase}-UI-SPEC.md` + +### ワークフロー：`/gsd-ui-review` + +**実行タイミング：** `/gsd-execute-phase` または `/gsd-verify-work` の後 — フロントエンドコードを含むプロジェクトで使用。 + +**スタンドアロン：** GSD 管理プロジェクトに限らず、あらゆるプロジェクトで動作します。UI-SPEC.md が存在しない場合は、抽象的な6ピラー基準に基づいて監査します。 + +**6ピラー（各1-4点）：** +1. コピーライティング — CTA ラベル、空状態、エラー状態 +2. ビジュアル — フォーカルポイント、ビジュアルヒエラルキー、アイコンのアクセシビリティ +3. カラー — アクセントカラーの使用規律、60/30/10 準拠 +4. タイポグラフィ — フォントサイズ/ウェイト制約の遵守 +5. スペーシング — グリッド整列、トークンの一貫性 +6. エクスペリエンスデザイン — ローディング/エラー/空状態のカバレッジ + +**出力：** フェーズディレクトリ内の `{padded_phase}-UI-REVIEW.md`（スコアと優先度の高い修正点トップ3）。 + +### 設定 + +| 設定 | デフォルト | 説明 | +|---------|---------|-------------| +| `workflow.ui_phase` | `true` | フロントエンドフェーズ用の UI デザインコントラクトを生成 | +| `workflow.ui_safety_gate` | `true` | plan-phase 時にフロントエンドフェーズで /gsd-ui-phase の実行を促す | + +どちらも「未設定＝有効」パターンに従います。`/gsd-settings` から無効化できます。 + +### shadcn の初期化 + +React/Next.js/Vite プロジェクトの場合、UI リサーチャーは `components.json` が見つからない場合に shadcn の初期化を提案します。フローは以下の通りです： + +1. `ui.shadcn.com/create` にアクセスしてプリセットを設定 +2. プリセット文字列をコピー +3. `npx shadcn init --preset {paste}` を実行 +4. プリセットはデザインシステム全体をエンコード — カラー、ボーダーラディウス、フォント + +プリセット文字列は GSD の第一級プランニングアーティファクトとなり、フェーズやマイルストーンをまたいで再現可能です。 + +### レジストリの安全性ゲート + +サードパーティの shadcn レジストリは任意のコードを注入できます。安全性ゲートでは以下が必要です： +- `npx shadcn view {component}` — インストール前に確認 +- `npx shadcn diff {component}` — 公式との比較 + +`workflow.ui_safety_gate` 設定トグルで制御します。 + +### スクリーンショットの保存 + +`/gsd-ui-review` は Playwright CLI を使用してスクリーンショットを `.planning/ui-reviews/` にキャプチャします。バイナリファイルが git に含まれないよう、`.gitignore` が自動的に作成されます。スクリーンショットは `/gsd-complete-milestone` 時にクリーンアップされます。 + +--- + +## バックログとスレッド + +### バックログパーキングロット + +アクティブなプランニングの準備ができていないアイデアは、999.x 番号を使用してバックログに格納され、アクティブなフェーズシーケンスの外に保持されます。 + +``` +/gsd-add-backlog "GraphQL API layer" # Creates 999.1-graphql-api-layer/ +/gsd-add-backlog "Mobile responsive" # Creates 999.2-mobile-responsive/ +``` + +バックログアイテムは完全なフェーズディレクトリを取得するため、`/gsd-discuss-phase 999.1` でアイデアをさらに探索したり、準備が整ったら `/gsd-plan-phase 999.1` を使用できます。 + +**レビューとプロモーション** は `/gsd-review-backlog` で行います — すべてのバックログアイテムを表示し、プロモーション（アクティブシーケンスへの移動）、保持（バックログに残す）、または削除を選択できます。 + +### シード + +シードは、トリガー条件を持つ将来を見据えたアイデアです。バックログアイテムとは異なり、適切なマイルストーンが到来すると自動的に表面化されます。 + +``` +/gsd-plant-seed "Add real-time collab when WebSocket infra is in place" +``` + +シードは完全な WHY と表面化タイミングを保持します。`/gsd-new-milestone` はすべてのシードをスキャンし、一致するものを提示します。 + +**保存場所：** `.planning/seeds/SEED-NNN-slug.md` + +### 永続コンテキストスレッド + +スレッドは、複数のセッションにまたがるが特定のフェーズに属さない作業のための、軽量なクロスセッション知識ストアです。 + +``` +/gsd-thread # List all threads +/gsd-thread fix-deploy-key-auth # Resume existing thread +/gsd-thread "Investigate TCP timeout" # Create new thread +``` + +スレッドは `/gsd-pause-work` より軽量です — フェーズ状態やプランコンテキストはありません。各スレッドファイルには Goal、Context、References、Next Steps セクションが含まれます。 + +スレッドは成熟した段階でフェーズ (`/gsd-add-phase`) やバックログアイテム (`/gsd-add-backlog`) にプロモーションできます。 + +**保存場所：** `.planning/threads/{slug}.md` + +--- + +## ワークストリーム + +ワークストリームを使うと、状態の衝突なしに複数のマイルストーン領域で並行作業できます。各ワークストリームは独立した `.planning/` 状態を持つため、切り替え時に進捗が上書きされることはありません。 + +**使用タイミング：** 異なる関心領域にまたがるマイルストーン機能（例：バックエンド API とフロントエンドダッシュボード）に取り組んでいて、コンテキストの混在なしに独立してプランニング・実行・ディスカッションしたい場合。 + +### コマンド + +| コマンド | 用途 | +|---------|---------| +| `/gsd-workstreams create ` | 独立したプランニング状態を持つ新しいワークストリームを作成 | +| `/gsd-workstreams switch ` | アクティブコンテキストを別のワークストリームに切り替え | +| `/gsd-workstreams list` | すべてのワークストリームとアクティブなものを表示 | +| `/gsd-workstreams complete ` | ワークストリームを完了としてマークし、状態をアーカイブ | + +### 動作の仕組み + +各ワークストリームは独自の `.planning/` ディレクトリサブツリーを維持します。ワークストリームを切り替えると、GSD はアクティブなプランニングコンテキストを入れ替え、`/gsd-progress`、`/gsd-discuss-phase`、`/gsd-plan-phase` などのコマンドがそのワークストリームの状態に対して動作するようにします。 + +これは `/gsd-new-workspace`（別のリポジトリワークツリーを作成）より軽量です。ワークストリームは同じコードベースと git 履歴を共有しつつ、プランニングアーティファクトを分離します。 + +--- + +## セキュリティ + +### 多層防御（v1.27） + +GSD はマークダウンファイルを生成し、それが LLM のシステムプロンプトとなります。これは、プランニングアーティファクトに流入するユーザー制御テキストが、潜在的な間接プロンプトインジェクションベクターであることを意味します。v1.27 では集中型セキュリティ強化が導入されました： + +**パストラバーサル防止：** +すべてのユーザー提供ファイルパス（`--text-file`、`--prd`）は、プロジェクトディレクトリ内に解決されることが検証されます。macOS の `/var` → `/private/var` シンボリックリンク解決にも対応しています。 + +**プロンプトインジェクション検出：** +`security.cjs` モジュールは、ユーザー提供テキストがプランニングアーティファクトに入る前に、既知のインジェクションパターン（ロールオーバーライド、インストラクションバイパス、system タグインジェクション）をスキャンします。 + +**ランタイムフック：** +- `gsd-prompt-guard.js` — `.planning/` への write/edit 呼び出しをインジェクションパターンでスキャン（常時有効、アドバイザリーのみ） +- `gsd-workflow-guard.js` — GSD ワークフローコンテキスト外でのファイル編集を警告（`hooks.workflow_guard` でオプトイン） + +**CI スキャナー：** +`prompt-injection-scan.test.cjs` は、すべてのエージェント、ワークフロー、コマンドファイルに埋め込まれたインジェクションベクターをスキャンします。テストスイートの一部として実行されます。 + +--- + +### 実行ウェーブの調整 + +``` + /gsd-execute-phase N + │ + ├── Analyze plan dependencies + │ + ├── Wave 1 (independent plans): + │ ├── Executor A (fresh 200K context) -> commit + │ └── Executor B (fresh 200K context) -> commit + │ + ├── Wave 2 (depends on Wave 1): + │ └── Executor C (fresh 200K context) -> commit + │ + └── Verifier + └── Check codebase against phase goals + │ + ├── PASS -> VERIFICATION.md (success) + └── FAIL -> Issues logged for /gsd-verify-work +``` + +### ブラウンフィールドワークフロー（既存コードベース） + +``` + /gsd-map-codebase + │ + ├── Stack Mapper -> codebase/STACK.md + ├── Arch Mapper -> codebase/ARCHITECTURE.md + ├── Convention Mapper -> codebase/CONVENTIONS.md + └── Concern Mapper -> codebase/CONCERNS.md + │ + ┌───────▼──────────┐ + │ /gsd-new-project │ <- Questions focus on what you're ADDING + └──────────────────┘ +``` + +--- + +## コマンドリファレンス + +### コアワークフロー + +| コマンド | 用途 | 使用タイミング | +|---------|---------|-------------| +| `/gsd-new-project` | フルプロジェクト初期化：質問、リサーチ、要件定義、ロードマップ | 新規プロジェクトの開始時 | +| `/gsd-new-project --auto @idea.md` | ドキュメントからの自動初期化 | PRD やアイデアドキュメントが準備済みの場合 | +| `/gsd-discuss-phase [N]` | 実装上の決定事項を記録 | プランニング前に、構築方法を決定するため | +| `/gsd-ui-phase [N]` | UI デザインコントラクトを生成 | discuss-phase の後、plan-phase の前（フロントエンドフェーズ） | +| `/gsd-plan-phase [N]` | リサーチ + プランニング + 検証 | フェーズ実行前 | +| `/gsd-execute-phase ` | すべてのプランを並列ウェーブで実行 | プランニング完了後 | +| `/gsd-verify-work [N]` | 自動診断付き手動 UAT | 実行完了後 | +| `/gsd-ship [N]` | 検証済みの作業から PR を作成 | 検証合格後 | +| `/gsd-fast ` | インラインの軽微なタスク — プランニングを完全にスキップ | タイプミス修正、設定変更、小規模リファクタリング | +| `/gsd-next` | 状態を自動検出して次のステップを実行 | いつでも — 「次に何をすべき？」 | +| `/gsd-ui-review [N]` | 遡及的6ピラービジュアル監査 | 実行後または verify-work 後（フロントエンドプロジェクト） | +| `/gsd-audit-milestone` | マイルストーンの完了定義を満たしているか検証 | マイルストーン完了前 | +| `/gsd-complete-milestone` | マイルストーンをアーカイブし、リリースタグを作成 | 全フェーズの検証完了後 | +| `/gsd-new-milestone [name]` | 次のバージョンサイクルを開始 | マイルストーン完了後 | + +### ナビゲーション + +| コマンド | 用途 | 使用タイミング | +|---------|---------|-------------| +| `/gsd-progress` | 状態と次のステップを表示 | いつでも -- 「今どこにいる？」 | +| `/gsd-resume-work` | 前回のセッションからフルコンテキストを復元 | 新しいセッションの開始時 | +| `/gsd-pause-work` | 構造化されたハンドオフを保存（HANDOFF.json + continue-here.md） | フェーズの途中で作業を中断する時 | +| `/gsd-session-report` | 作業内容と成果を含むセッションサマリーを生成 | セッション終了時、ステークホルダーへの共有時 | +| `/gsd-help` | すべてのコマンドを表示 | クイックリファレンス | +| `/gsd-update` | 変更履歴プレビュー付きで GSD を更新 | 新バージョンの確認時 | +| `/gsd-join-discord` | Discord コミュニティの招待リンクを開く | 質問やコミュニティ参加時 | + +### フェーズ管理 + +| コマンド | 用途 | 使用タイミング | +|---------|---------|-------------| +| `/gsd-add-phase` | ロードマップに新しいフェーズを追加 | 初期プランニング後にスコープが拡大した場合 | +| `/gsd-insert-phase [N]` | 緊急作業を挿入（小数番号） | マイルストーン中の緊急修正 | +| `/gsd-remove-phase [N]` | 将来のフェーズを削除して番号を振り直す | 機能のスコープ縮小 | +| `/gsd-list-phase-assumptions [N]` | OpenCode の意図するアプローチをプレビュー | プランニング前に方向性を確認 | +| `/gsd-plan-milestone-gaps` | 監査ギャップに対するフェーズを作成 | 監査で不足項目が見つかった後 | +| `/gsd-research-phase [N]` | エコシステムの深いリサーチのみ | 複雑または不慣れなドメイン | + +### ブラウンフィールドとユーティリティ + +| コマンド | 用途 | 使用タイミング | +|---------|---------|-------------| +| `/gsd-map-codebase` | 既存コードベースを分析 | 既存コードに対する `/gsd-new-project` の前 | +| `/gsd-quick` | GSD 保証付きのアドホックタスク | バグ修正、小機能、設定変更 | +| `/gsd-debug [desc]` | 永続状態を持つ体系的デバッグ | 何かが壊れた時 | +| `/gsd-forensics` | ワークフロー障害の診断レポート | 状態、アーティファクト、git 履歴が破損していると思われる場合 | +| `/gsd-add-todo [desc]` | 後でやるアイデアを記録 | セッション中にアイデアが浮かんだ時 | +| `/gsd-check-todos` | 保留中の TODO を一覧表示 | 記録したアイデアのレビュー | +| `/gsd-settings` | ワークフロートグルとモデルプロファイルを設定 | モデル変更、エージェントのトグル | +| `/gsd-set-profile ` | クイックプロファイル切り替え | コスト/品質トレードオフの変更 | +| `/gsd-reapply-patches` | アップデート後にローカル変更を復元 | ローカル編集がある場合の `/gsd-update` 後 | + +### コード品質とレビュー + +| コマンド | 用途 | 使用タイミング | +|---------|---------|-------------| +| `/gsd-review --phase N` | 外部 CLI からのクロス AI ピアレビュー | 実行前にプランを検証 | +| `/gsd-pr-branch` | `.planning/` コミットをフィルタリングしたクリーンな PR ブランチ | プランニングフリーの diff で PR を作成する前 | +| `/gsd-audit-uat` | 全フェーズの検証負債を監査 | マイルストーン完了前 | + +### バックログとスレッド + +| コマンド | 用途 | 使用タイミング | +|---------|---------|-------------| +| `/gsd-add-backlog ` | バックログパーキングロットにアイデアを追加（999.x） | アクティブなプランニングの準備ができていないアイデア | +| `/gsd-review-backlog` | バックログアイテムのプロモーション/保持/削除 | 新マイルストーン前の優先順位付け | +| `/gsd-plant-seed ` | トリガー条件付きの将来を見据えたアイデア | 将来のマイルストーンで表面化すべきアイデア | +| `/gsd-thread [name]` | 永続コンテキストスレッド | フェーズ構造外のクロスセッション作業 | + +--- + +## 設定リファレンス + +GSD はプロジェクト設定を `.planning/config.json` に保存します。`/gsd-new-project` 時に設定するか、後から `/gsd-settings` で更新できます。 + +### 完全な config.json スキーマ + +```json +{ + "mode": "interactive", + "granularity": "standard", + "model_profile": "balanced", + "planning": { + "commit_docs": true, + "search_gitignored": false + }, + "workflow": { + "research": true, + "plan_check": true, + "verifier": true, + "nyquist_validation": true, + "ui_phase": true, + "ui_safety_gate": true, + "research_before_questions": false, + "discuss_mode": "standard", + "skip_discuss": false + }, + "resolve_model_ids": "anthropic", + "hooks": { + "context_warnings": true, + "workflow_guard": false + }, + "git": { + "branching_strategy": "none", + "phase_branch_template": "gsd/phase-{phase}-{slug}", + "milestone_branch_template": "gsd/{milestone}-{slug}", + "quick_branch_template": null + } +} +``` + +### コア設定 + +| 設定 | オプション | デフォルト | 制御内容 | +|---------|---------|---------|------------------| +| `mode` | `interactive`, `yolo` | `interactive` | `yolo` は決定を自動承認、`interactive` は各ステップで確認 | +| `granularity` | `coarse`, `standard`, `fine` | `standard` | フェーズの粒度：スコープの分割の細かさ（3-5、5-8、または 8-12 フェーズ） | +| `model_profile` | `quality`, `balanced`, `budget`, `inherit` | `balanced` | 各エージェントのモデルティア（下表を参照） | + +### プランニング設定 + +| 設定 | オプション | デフォルト | 制御内容 | +|---------|---------|---------|------------------| +| `planning.commit_docs` | `true`, `false` | `true` | `.planning/` ファイルを git にコミットするかどうか | +| `planning.search_gitignored` | `true`, `false` | `false` | `.planning/` を含めるためにブロード検索に `--no-ignore` を追加 | + +> **注：** `.planning/` が `.gitignore` に含まれている場合、設定値に関係なく `commit_docs` は自動的に `false` になります。 + +### ワークフロートグル + +| 設定 | オプション | デフォルト | 制御内容 | +|---------|---------|---------|------------------| +| `workflow.research` | `true`, `false` | `true` | プランニング前のドメイン調査 | +| `workflow.plan_check` | `true`, `false` | `true` | プラン検証ループ（最大3回） | +| `workflow.verifier` | `true`, `false` | `true` | 実行後のフェーズ目標に対する検証 | +| `workflow.nyquist_validation` | `true`, `false` | `true` | plan-phase 時のバリデーションアーキテクチャリサーチ、8番目の plan-check 次元 | +| `workflow.ui_phase` | `true`, `false` | `true` | フロントエンドフェーズ用の UI デザインコントラクトを生成 | +| `workflow.ui_safety_gate` | `true`, `false` | `true` | plan-phase 時にフロントエンドフェーズで /gsd-ui-phase の実行を促す | +| `workflow.research_before_questions` | `true`, `false` | `false` | ディスカッション質問の後ではなく前にリサーチを実行 | +| `workflow.discuss_mode` | `standard`, `assumptions` | `standard` | ディスカッションスタイル：オープンエンドの質問 vs. コードベース駆動の前提確認 | +| `workflow.skip_discuss` | `true`, `false` | `false` | 自律モードで discuss-phase を完全にスキップ、ROADMAP のフェーズ目標から最小限の CONTEXT.md を作成 | + +### フック設定 + +| 設定 | オプション | デフォルト | 制御内容 | +|---------|---------|---------|------------------| +| `hooks.context_warnings` | `true`, `false` | `true` | コンテキストウィンドウ使用量の警告 | +| `hooks.workflow_guard` | `true`, `false` | `false` | GSD ワークフローコンテキスト外でのファイル編集の警告 | + +慣れたドメインやトークン節約時に、ワークフロートグルを無効にしてフェーズを高速化できます。 + +### Git ブランチ戦略 + +| 設定 | オプション | デフォルト | 制御内容 | +|---------|---------|---------|------------------| +| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | ブランチ作成のタイミングと方法 | +| `git.phase_branch_template` | テンプレート文字列 | `gsd/phase-{phase}-{slug}` | phase 戦略のブランチ名 | +| `git.milestone_branch_template` | テンプレート文字列 | `gsd/{milestone}-{slug}` | milestone 戦略のブランチ名 | +| `git.quick_branch_template` | テンプレート文字列 または `null` | `null` | `/gsd-quick` タスク用のオプションブランチ名 | + +**ブランチ戦略の説明：** + +| 戦略 | ブランチ作成 | スコープ | 最適な用途 | +|----------|---------------|-------|----------| +| `none` | なし | N/A | ソロ開発、シンプルなプロジェクト | +| `phase` | 各 `execute-phase` 時 | フェーズごとに1ブランチ | フェーズごとのコードレビュー、粒度の細かいロールバック | +| `milestone` | 最初の `execute-phase` 時 | 全フェーズで1ブランチを共有 | リリースブランチ、バージョンごとの PR | + +**テンプレート変数：** `{phase}` = ゼロパディングされた番号（例："03"）、`{slug}` = 小文字ハイフン区切りの名前、`{milestone}` = バージョン（例："v1.0"）、`{num}` / `{quick}` = quick タスク ID（例："260317-abc"）。 + +quick タスクのブランチ設定例： + +```json +"git": { + "quick_branch_template": "gsd/quick-{num}-{slug}" +} +``` + +### モデルプロファイル（エージェント別の内訳） + +| エージェント | `quality` | `balanced` | `budget` | `inherit` | +|-------|-----------|------------|----------|-----------| +| gsd-planner | Opus | Opus | Sonnet | Inherit | +| gsd-roadmapper | Opus | Sonnet | Sonnet | Inherit | +| gsd-executor | Opus | Sonnet | Sonnet | Inherit | +| gsd-phase-researcher | Opus | Sonnet | Haiku | Inherit | +| gsd-project-researcher | Opus | Sonnet | Haiku | Inherit | +| gsd-research-synthesizer | Sonnet | Sonnet | Haiku | Inherit | +| gsd-debugger | Opus | Sonnet | Sonnet | Inherit | +| gsd-codebase-mapper | Sonnet | Haiku | Haiku | Inherit | +| gsd-verifier | Sonnet | Sonnet | Haiku | Inherit | +| gsd-plan-checker | Sonnet | Sonnet | Haiku | Inherit | +| gsd-integration-checker | Sonnet | Sonnet | Haiku | Inherit | + +**プロファイルの方針：** +- **quality** -- すべての意思決定エージェントに Opus、読み取り専用の検証に Sonnet。クォータに余裕があり、重要な作業に使用。 +- **balanced** -- プランニング（アーキテクチャの決定が行われる場所）にのみ Opus、それ以外は Sonnet。正当な理由があるデフォルト。 +- **budget** -- コードを書くものには Sonnet、リサーチと検証には Haiku。大量作業や重要度の低いフェーズに使用。 +- **inherit** -- すべてのエージェントが現在のセッションモデルを使用。モデルを動的に切り替える場合（例：OpenCode の `/model`）や、OpenCode を非 Anthropic プロバイダー（OpenRouter、ローカルモデル）で使用する場合に最適で、予期しない API コストを回避できます。非 OpenCode ランタイム（Codex、OpenCode、Gemini CLI）では、インストーラーが自動的に `resolve_model_ids: "omit"` を設定します -- [非 OpenCode ランタイムの使用](#非-OpenCode-ランタイムの使用codexopencodegemini-cli)を参照。 + +--- + +## 使用例 + +### 新規プロジェクト（フルサイクル） + +```bash +OpenCode --dangerously-skip-permissions +/gsd-new-project # 質問に回答、設定、ロードマップを承認 +/new +/gsd-discuss-phase 1 # 好みを確定 +/gsd-ui-phase 1 # デザインコントラクト（フロントエンドフェーズ） +/gsd-plan-phase 1 # リサーチ + プラン + 検証 +/gsd-execute-phase 1 # 並列実行 +/gsd-verify-work 1 # 手動 UAT +/gsd-ship 1 # 検証済み作業から PR を作成 +/gsd-ui-review 1 # ビジュアル監査（フロントエンドフェーズ） +/new +/gsd-next # 自動検出して次のステップを実行 +... +/gsd-audit-milestone # すべて出荷されたか確認 +/gsd-complete-milestone # アーカイブ、タグ付け、完了 +/gsd-session-report # セッションサマリーを生成 +``` + +### 既存ドキュメントからの新規プロジェクト + +```bash +/gsd-new-project --auto @prd.md # ドキュメントからリサーチ/要件/ロードマップを自動実行 +/new +/gsd-discuss-phase 1 # ここから通常のフロー +``` + +### 既存コードベース + +```bash +/gsd-map-codebase # 既存のコードを分析（並列エージェント） +/gsd-new-project # 追加する内容に焦点を当てた質問 +# （ここから通常のフェーズワークフロー） +``` + +### クイックバグ修正 + +```bash +/gsd-quick +> "Fix the login button not responding on mobile Safari" +``` + +### 休憩後の再開 + +```bash +/gsd-progress # 前回の続きと次のステップを確認 +# または +/gsd-resume-work # 前回のセッションからフルコンテキストを復元 +``` + +### リリース準備 + +```bash +/gsd-audit-milestone # 要件カバレッジを確認、スタブを検出 +/gsd-plan-milestone-gaps # 監査でギャップが見つかった場合、フェーズを作成して埋める +/gsd-complete-milestone # アーカイブ、タグ付け、完了 +``` + +### スピード vs 品質プリセット + +| シナリオ | モード | 粒度 | プロファイル | リサーチ | プランチェック | ベリファイア | +|----------|------|-------|---------|----------|------------|----------| +| プロトタイピング | `yolo` | `coarse` | `budget` | オフ | オフ | オフ | +| 通常開発 | `interactive` | `standard` | `balanced` | オン | オン | オン | +| プロダクション | `interactive` | `fine` | `quality` | オン | オン | オン | + +**自律モードでの discuss-phase スキップ：** `yolo` モードで実行中に、PROJECT.md に既に十分な設定が記録されている場合は、`/gsd-settings` で `workflow.skip_discuss: true` を設定してください。これにより discuss-phase を完全にバイパスし、ROADMAP のフェーズ目標から最小限の CONTEXT.md を作成します。PROJECT.md と規約がディスカッションで新しい情報を追加しないほど包括的な場合に有用です。 + +### マイルストーン中のスコープ変更 + +```bash +/gsd-add-phase # ロードマップに新しいフェーズを追加 +# または +/gsd-insert-phase 3 # フェーズ 3 と 4 の間に緊急作業を挿入 +# または +/gsd-remove-phase 7 # フェーズ 7 をスコープ外にして番号を振り直す +``` + +### マルチプロジェクトワークスペース + +独立した GSD 状態を持つ複数のリポジトリや機能で並行作業できます。 + +```bash +# モノレポからリポジトリを含むワークスペースを作成 +/gsd-new-workspace --name feature-b --repos hr-ui,ZeymoAPI + +# フィーチャーブランチの分離 — 独自の .planning/ を持つ現在のリポジトリのワークツリー +/gsd-new-workspace --name feature-b --repos . + +# ワークスペースに移動して GSD を初期化 +cd ~/gsd-workspaces/feature-b +/gsd-new-project + +# ワークスペースの一覧と管理 +/gsd-list-workspaces +/gsd-remove-workspace feature-b +``` + +各ワークスペースには以下が含まれます： +- 独自の `.planning/` ディレクトリ（ソースリポジトリから完全に独立） +- 指定されたリポジトリの Git ワークツリー（デフォルト）またはクローン +- メンバーリポジトリを追跡する `WORKSPACE.md` マニフェスト + +--- + +## トラブルシューティング + +### 「Project already initialized」 + +`/gsd-new-project` を実行したが、`.planning/PROJECT.md` が既に存在しています。これは安全チェックです。やり直したい場合は、まず `.planning/` ディレクトリを削除してください。 + +### 長時間セッションでのコンテキスト劣化 + +主要なコマンド間でコンテキストウィンドウをクリアしてください：OpenCode では `/new` を使用します。GSD はフレッシュなコンテキストを前提に設計されています — すべてのサブエージェントはクリーンな 200K ウィンドウを取得します。メインセッションで品質が低下している場合は、クリアして `/gsd-resume-work` または `/gsd-progress` で状態を復元してください。 + +### プランが誤っている、または方向性がずれている + +プランニング前に `/gsd-discuss-phase [N]` を実行してください。プランの品質問題のほとんどは、CONTEXT.md があれば防げたはずの前提を OpenCode が置いてしまうことに起因します。`/gsd-list-phase-assumptions [N]` を使用して、プランにコミットする前に OpenCode の意図を確認することもできます。 + +### 実行が失敗する、またはスタブが生成される + +プランが野心的すぎなかったか確認してください。プランは最大2-3タスクにすべきです。タスクが大きすぎると、単一のコンテキストウィンドウで確実に生成できる範囲を超えてしまいます。より小さなスコープで再プランニングしてください。 + +### 現在地がわからなくなった + +`/gsd-progress` を実行してください。すべての状態ファイルを読み込み、現在地と次にやるべきことを正確に教えてくれます。 + +### 実行後に変更が必要 + +`/gsd-execute-phase` を再実行しないでください。ターゲットを絞った修正には `/gsd-quick` を使用するか、`/gsd-verify-work` で体系的に問題を特定し UAT を通じて修正してください。 + +### モデルのコストが高すぎる + +budget プロファイルに切り替えてください：`/gsd-set-profile budget`。ドメインに慣れている場合（またはOpenCode が慣れている場合）は、`/gsd-settings` でリサーチエージェントと plan-check エージェントを無効にしてください。 + +### 非 OpenCode ランタイムの使用（Codex、OpenCode、Gemini CLI） + +非 OpenCode ランタイム用に GSD をインストールした場合、インストーラーがモデル解決を設定済みのため、すべてのエージェントがランタイムのデフォルトモデルを使用します。手動設定は不要です。具体的には、インストーラーが設定に `resolve_model_ids: "omit"` を設定し、GSD に Anthropic モデル ID の解決をスキップしてランタイム独自のデフォルトモデルを使用するよう指示します。 + +非 OpenCode ランタイムで異なるエージェントに異なるモデルを割り当てるには、ランタイムが認識する完全修飾モデル ID を使用して `.planning/config.json` に `model_overrides` を追加します： + +```json +{ + "resolve_model_ids": "omit", + "model_overrides": { + "gsd-planner": "o3", + "gsd-executor": "o4-mini", + "gsd-debugger": "o3" + } +} +``` + +インストーラーは Gemini CLI、OpenCode、Codex 用に `resolve_model_ids: "omit"` を自動設定します。非 OpenCode ランタイムを手動で設定する場合は、`.planning/config.json` に自分で追加してください。 + +完全な説明は[設定リファレンス](../CONFIGURATION.md#non-OpenCode-runtimes-codex-opencode-gemini-cli)をご覧ください。 + +### 非 Anthropic プロバイダーでの OpenCode の使用（OpenRouter、ローカル） + +GSD サブエージェントが Anthropic モデルを呼び出し、OpenRouter やローカルプロバイダーを通じて支払っている場合は、`inherit` プロファイルに切り替えてください：`/gsd-set-profile inherit`。これにより、すべてのエージェントが特定の Anthropic モデルの代わりに現在のセッションモデルを使用します。`/gsd-settings` → モデルプロファイル → Inherit も参照してください。 + +### 機密/プライベートプロジェクトでの作業 + +`/gsd-new-project` 時または `/gsd-settings` で `commit_docs: false` を設定してください。`.planning/` を `.gitignore` に追加してください。プランニングアーティファクトはローカルに保持され、git に含まれません。 + +### GSD アップデートがローカル変更を上書きした + +v1.17 以降、インストーラーはローカルで変更されたファイルを `gsd-local-patches/` にバックアップします。`/gsd-reapply-patches` を実行して変更をマージし直してください。 + +### ワークフロー診断 (`/gsd-forensics`) + +ワークフローが明確でない形で失敗した場合 -- プランが存在しないファイルを参照する、実行が予期しない結果を生成する、状態が破損しているように見える -- `/gsd-forensics` を実行して診断レポートを生成してください。 + +**チェック内容：** +- Git 履歴の異常（孤立コミット、予期しないブランチ状態、rebase アーティファクト） +- アーティファクトの整合性（欠落または不正なプランニングファイル、壊れた相互参照） +- 状態の不整合（ROADMAP のステータスと実際のファイル存在の不一致、設定のドリフト） + +**出力：** `.planning/forensics/` に書き出される診断レポート。検出事項と推奨される修復手順が含まれます。 + +### サブエージェントが失敗したように見えるが作業は完了している + +OpenCode の分類バグに対する既知の回避策があります。GSD のオーケストレーター（execute-phase、quick）は、失敗を報告する前に実際の出力をスポットチェックします。失敗メッセージが表示されてもコミットが作成されている場合は、`git log` を確認してください -- 作業は成功している可能性があります。 + +### 並列実行によるビルドロックエラー + +並列ウェーブ実行中に pre-commit フックの失敗、cargo ロックの競合、30分以上の実行時間が発生した場合、これは複数のエージェントが同時にビルドツールをトリガーすることが原因です。GSD は v1.26 以降これを自動的に処理します — 並列エージェントはコミット時に `--no-verify` を使用し、オーケストレーターが各ウェーブ後にフックを1回実行します。古いバージョンを使用している場合は、プロジェクトの `AGENTS.md` に以下を追加してください： + +```markdown +## Git Commit Rules for Agents +All subagent/executor commits MUST use `--no-verify`. +``` + +並列実行を完全に無効にするには：`/gsd-settings` → `parallelization.enabled` を `false` に設定。 + +### Windows：保護されたディレクトリでインストールがクラッシュする + +Windows でインストーラーが `EPERM: operation not permitted, scandir` でクラッシュした場合、これは OS で保護されたディレクトリ（例：Chromium ブラウザプロファイル）が原因です。v1.24 以降修正済み — 最新バージョンに更新してください。回避策として、インストーラー実行前に問題のあるディレクトリを一時的にリネームしてください。 + +--- + +## リカバリークイックリファレンス + +| 問題 | 解決策 | +|---------|----------| +| コンテキストの喪失 / 新セッション | `/gsd-resume-work` または `/gsd-progress` | +| フェーズが失敗した | フェーズのコミットを `git revert` して再プランニング | +| スコープ変更が必要 | `/gsd-add-phase`、`/gsd-insert-phase`、または `/gsd-remove-phase` | +| マイルストーン監査でギャップを発見 | `/gsd-plan-milestone-gaps` | +| 何かが壊れた | `/gsd-debug "description"` | +| ワークフロー状態が破損している可能性 | `/gsd-forensics` | +| ターゲットを絞った修正 | `/gsd-quick` | +| プランがビジョンに合わない | `/gsd-discuss-phase [N]` で再プランニング | +| コストが高い | `/gsd-set-profile budget` と `/gsd-settings` でエージェントをオフ | +| アップデートがローカル変更を壊した | `/gsd-reapply-patches` | +| ステークホルダー向けセッションサマリーが欲しい | `/gsd-session-report` | +| 次のステップがわからない | `/gsd-next` | +| 並列実行でビルドエラー | GSD を更新するか `parallelization.enabled: false` を設定 | + +--- + +## プロジェクトファイル構造 + +参考として、GSD がプロジェクトに作成するファイル構造を示します： + +``` +.planning/ + PROJECT.md # プロジェクトのビジョンとコンテキスト（常に読み込まれる） + REQUIREMENTS.md # スコープ付き v1/v2 要件（ID 付き） + ROADMAP.md # ステータス追跡付きフェーズ分割 + STATE.md # 決定事項、ブロッカー、セッションメモリ + config.json # ワークフロー設定 + MILESTONES.md # 完了したマイルストーンのアーカイブ + HANDOFF.json # 構造化セッション引き継ぎ（/gsd-pause-work から） + research/ # /gsd-new-project からのドメインリサーチ + reports/ # セッションレポート（/gsd-session-report から） + todos/ + pending/ # 作業待ちのキャプチャされたアイデア + done/ # 完了した TODO + debug/ # アクティブなデバッグセッション + resolved/ # アーカイブされたデバッグセッション + codebase/ # ブラウンフィールドコードベースマッピング（/gsd-map-codebase から） + phases/ + XX-phase-name/ + XX-YY-PLAN.md # アトミック実行プラン + XX-YY-SUMMARY.md # 実行結果と決定事項 + CONTEXT.md # 実装の好み + RESEARCH.md # エコシステムリサーチの成果 + VERIFICATION.md # 実行後の検証結果 + XX-UI-SPEC.md # UI デザインコントラクト（/gsd-ui-phase から） + XX-UI-REVIEW.md # ビジュアル監査スコア（/gsd-ui-review から） + ui-reviews/ # /gsd-ui-review からのスクリーンショット（gitignore 対象） +``` diff --git a/gsd-opencode/docs/ja-JP/context-monitor.md b/gsd-opencode/docs/ja-JP/context-monitor.md new file mode 100644 index 0000000..706ae4a --- /dev/null +++ b/gsd-opencode/docs/ja-JP/context-monitor.md @@ -0,0 +1,115 @@ +# コンテキストウィンドウモニター + +ツール使用後に実行されるフック（OpenCode では `PostToolUse`、Gemini CLI では `AfterTool`）で、コンテキストウィンドウの使用量が高くなった際にエージェントに警告します。 + +## 課題 + +ステータスラインはコンテキスト使用量を**ユーザー**に表示しますが、**エージェント**自身はコンテキストの制限を認識していません。コンテキストが不足すると、エージェントは限界に達するまで作業を続行し、タスクの途中で状態を保存できないまま停止する可能性があります。 + +## 仕組み + +1. ステータスラインフックがコンテキストメトリクスを `/tmp/OpenCode-ctx-{session_id}.json` に書き込む +2. 各ツール使用後、コンテキストモニターがこのメトリクスを読み取る +3. 残りコンテキストがしきい値を下回ると、`additionalContext` として警告を注入する +4. エージェントが会話内で警告を受け取り、適切に対応できる + +## しきい値 + +| レベル | 残量 | エージェントの動作 | +|--------|------|------------------| +| Normal | > 35% | 警告なし | +| WARNING | <= 35% | 現在のタスクをまとめ、新しい複雑な作業の開始を避ける | +| CRITICAL | <= 25% | 即座に停止し、状態を保存する（`/gsd-pause-work`） | + +## デバウンス + +エージェントへの繰り返し警告を防ぐため: +- 最初の警告は即座に発火 +- 以降の警告は間に5回のツール使用が必要 +- 深刻度のエスカレーション（WARNING -> CRITICAL）はデバウンスをバイパス + +## アーキテクチャ + +``` +ステータスラインフック (gsd-statusline.js) + | 書き込み + v +/tmp/OpenCode-ctx-{session_id}.json + ^ 読み取り + | +コンテキストモニター (gsd-context-monitor.js, PostToolUse/AfterTool) + | 注入 + v +additionalContext -> エージェントが警告を確認 +``` + +ブリッジファイルはシンプルな JSON オブジェクトです: + +```json +{ + "session_id": "abc123", + "remaining_percentage": 28.5, + "used_pct": 71, + "timestamp": 1708200000 +} +``` + +## GSD との統合 + +GSD の `/gsd-pause-work` コマンドは実行状態を保存します。WARNING メッセージはこのコマンドの使用を提案し、CRITICAL メッセージは即座の状態保存を指示します。 + +## セットアップ + +両フックは `npx gsd-opencode` のインストール時に自動的に登録されます: + +- **ステータスライン**（ブリッジファイルの書き込み）: settings.json の `statusLine` として登録 +- **コンテキストモニター**（ブリッジファイルの読み取り）: settings.json の `PostToolUse` フックとして登録（Gemini では `AfterTool`） + +`$HOME/.config/opencode/settings.json`（OpenCode）への手動登録: + +```json +{ + "statusLine": { + "type": "command", + "command": "node $HOME/.config/opencode/hooks/gsd-statusline.js" + }, + "hooks": { + "PostToolUse": [ + { + "hooks": [ + { + "type": "command", + "command": "node $HOME/.config/opencode/hooks/gsd-context-monitor.js" + } + ] + } + ] + } +} +``` + +Gemini CLI（`~/.gemini/settings.json`）の場合、`PostToolUse` の代わりに `AfterTool` を使用します: + +```json +{ + "hooks": { + "AfterTool": [ + { + "hooks": [ + { + "type": "command", + "command": "node ~/.gemini/hooks/gsd-context-monitor.js" + } + ] + } + ] + } +} +``` + +## 安全性 + +- フックは全体を try/catch で囲み、エラー時はサイレントに終了 +- ツール実行をブロックしない — モニターの故障がエージェントのワークフローを壊してはならない +- 古いメトリクス（60秒以上前）は無視 +- ブリッジファイルが存在しない場合も正常に処理（サブエージェント、新規セッション） diff --git a/gsd-opencode/docs/ja-JP/superpowers/plans/2026-03-18-materialize-new-project-config.md b/gsd-opencode/docs/ja-JP/superpowers/plans/2026-03-18-materialize-new-project-config.md new file mode 100644 index 0000000..52da7af --- /dev/null +++ b/gsd-opencode/docs/ja-JP/superpowers/plans/2026-03-18-materialize-new-project-config.md @@ -0,0 +1,699 @@ +# 初期化時に new-project の設定を完全展開する + +> **エージェント型ワーカー向け:** 必須サブスキル: superpowers:subagent-driven-development（推奨）または superpowers:executing-plans を使用して、このプランをタスクごとに実装してください。各ステップはチェックボックス（`- [ ]`）構文で進捗を追跡します。 + +**目標:** `/gsd-new-project` が `.planning/config.json` を作成する際、ユーザーが選択した6つのキーだけでなく、すべての有効なデフォルト値を含むファイルを生成する。これにより、開発者はソースコードを読まなくてもすべての設定を確認できるようになる。 + +**アーキテクチャ:** `config.cjs` に単一の JS 関数 `buildNewProjectConfig(cwd, userChoices)` を追加し、新規プロジェクトの完全な設定の唯一の信頼できる情報源とする。これを CLI コマンド `config-new-project` として公開する。`new-project.md` ワークフローを更新し、部分的な JSON をインラインで書き込む代わりにこのコマンドを呼び出すようにする。 + +**技術スタック:** Node.js/CommonJS、既存の gsd-tools CLI、テストには `node:test` を使用。 + +--- + +## 背景: 現在の状態 + +`new-project.md` のステップ 5 では、以下の部分的な設定を書き込む（AI がテンプレートを埋める）: + +```json +{ + "mode": "...", "granularity": "...", "parallelization": "...", + "commit_docs": "...", "model_profile": "...", + "workflow": { "research", "plan_check", "verifier", "nyquist_validation" } +} +``` + +欠落しているキーは実行時に `loadConfig()` が暗黙的に解決する: + +- `search_gitignored: false` +- `brave_search: false`（または環境検出による `true`） +- `git.branching_strategy: "none"` +- `git.phase_branch_template: "gsd/phase-{phase}-{slug}"` +- `git.milestone_branch_template: "gsd/{milestone}-{slug}"` + +最初から存在すべき完全な設定: + +```json +{ + "mode": "yolo|interactive", + "granularity": "coarse|standard|fine", + "model_profile": "balanced", + "commit_docs": true, + "parallelization": true, + "search_gitignored": false, + "brave_search": false, + "git": { + "branching_strategy": "none", + "phase_branch_template": "gsd/phase-{phase}-{slug}", + "milestone_branch_template": "gsd/{milestone}-{slug}" + }, + "workflow": { + "research": true, + "plan_check": true, + "verifier": true, + "nyquist_validation": true + } +} +``` + +--- + +## ファイルマップ + +| ファイル | 操作 | 目的 | +|------|--------|---------| +| `get-shit-done/bin/lib/config.cjs` | 変更 | `buildNewProjectConfig()` + `cmdConfigNewProject()` を追加 | +| `get-shit-done/bin/gsd-tools.cjs` | 変更 | `config-new-project` の case を登録 + usage 文字列を更新 | +| `get-shit-done/workflows/new-project.md` | 変更 | ステップ 2a + 5: インライン JSON 書き込みを CLI 呼び出しに置換 | +| `tests/config.test.cjs` | 変更 | `config-new-project` テストスイートを追加 | + +--- + +## タスク 1: `buildNewProjectConfig` と `cmdConfigNewProject` を config.cjs に追加 + +**ファイル:** + +- 変更: `get-shit-done/bin/lib/config.cjs` + +- [ ] **ステップ 1.1: まず失敗するテストを書く** + +`tests/config.test.cjs` に追加する（`config-get` スイートの後、`module.exports` の前）: + +```js +// ─── config-new-project ────────────────────────────────────────────────────── + +describe('config-new-project command', () => { + let tmpDir; + + beforeEach(() => { + tmpDir = createTempProject(); + }); + + afterEach(() => { + cleanup(tmpDir); + }); + + test('creates full config with all expected top-level and nested keys', () => { + const choices = JSON.stringify({ + mode: 'interactive', + granularity: 'standard', + parallelization: true, + commit_docs: true, + model_profile: 'balanced', + workflow: { research: true, plan_check: true, verifier: true, nyquist_validation: true }, + }); + const result = runGsdTools(['config-new-project', choices], tmpDir); + assert.ok(result.success, `Command failed: ${result.error}`); + + const config = readConfig(tmpDir); + + // ユーザーの選択が反映されている + assert.strictEqual(config.mode, 'interactive'); + assert.strictEqual(config.granularity, 'standard'); + assert.strictEqual(config.parallelization, true); + assert.strictEqual(config.commit_docs, true); + assert.strictEqual(config.model_profile, 'balanced'); + + // デフォルト値が展開されている + assert.strictEqual(typeof config.search_gitignored, 'boolean'); + assert.strictEqual(typeof config.brave_search, 'boolean'); + + // git セクションが3つのキーすべてを持つ + assert.ok(config.git && typeof config.git === 'object', 'git section should exist'); + assert.strictEqual(config.git.branching_strategy, 'none'); + assert.strictEqual(config.git.phase_branch_template, 'gsd/phase-{phase}-{slug}'); + assert.strictEqual(config.git.milestone_branch_template, 'gsd/{milestone}-{slug}'); + + // workflow セクションが4つのキーすべてを持つ + assert.ok(config.workflow && typeof config.workflow === 'object', 'workflow section should exist'); + assert.strictEqual(config.workflow.research, true); + assert.strictEqual(config.workflow.plan_check, true); + assert.strictEqual(config.workflow.verifier, true); + assert.strictEqual(config.workflow.nyquist_validation, true); + }); + + test('user choices override defaults', () => { + const choices = JSON.stringify({ + mode: 'yolo', + granularity: 'coarse', + parallelization: false, + commit_docs: false, + model_profile: 'quality', + workflow: { research: false, plan_check: false, verifier: true, nyquist_validation: false }, + }); + const result = runGsdTools(['config-new-project', choices], tmpDir); + assert.ok(result.success, `Command failed: ${result.error}`); + + const config = readConfig(tmpDir); + assert.strictEqual(config.mode, 'yolo'); + assert.strictEqual(config.granularity, 'coarse'); + assert.strictEqual(config.parallelization, false); + assert.strictEqual(config.commit_docs, false); + assert.strictEqual(config.model_profile, 'quality'); + assert.strictEqual(config.workflow.research, false); + assert.strictEqual(config.workflow.plan_check, false); + assert.strictEqual(config.workflow.verifier, true); + assert.strictEqual(config.workflow.nyquist_validation, false); + // 未選択のキーにもデフォルト値が設定されている + assert.strictEqual(config.git.branching_strategy, 'none'); + assert.strictEqual(typeof config.search_gitignored, 'boolean'); + }); + + test('works with empty choices — all defaults materialized', () => { + const result = runGsdTools(['config-new-project', '{}'], tmpDir); + assert.ok(result.success, `Command failed: ${result.error}`); + + const config = readConfig(tmpDir); + assert.strictEqual(config.model_profile, 'balanced'); + assert.strictEqual(config.commit_docs, true); + assert.strictEqual(config.parallelization, true); + assert.strictEqual(config.search_gitignored, false); + assert.ok(config.git && typeof config.git === 'object'); + assert.strictEqual(config.git.branching_strategy, 'none'); + assert.ok(config.workflow && typeof config.workflow === 'object'); + assert.strictEqual(config.workflow.nyquist_validation, true); + }); + + test('is idempotent — returns already_exists if config exists', () => { + // 1回目の呼び出し: 作成 + const choices = JSON.stringify({ mode: 'yolo', granularity: 'fine' }); + const first = runGsdTools(['config-new-project', choices], tmpDir); + assert.ok(first.success, `First call failed: ${first.error}`); + const firstOut = JSON.parse(first.output); + assert.strictEqual(firstOut.created, true); + + // 2回目の呼び出し: 冪等性の確認 + const second = runGsdTools(['config-new-project', choices], tmpDir); + assert.ok(second.success, `Second call failed: ${second.error}`); + const secondOut = JSON.parse(second.output); + assert.strictEqual(secondOut.created, false); + assert.strictEqual(secondOut.reason, 'already_exists'); + + // 設定が変更されていない + const config = readConfig(tmpDir); + assert.strictEqual(config.mode, 'yolo'); + assert.strictEqual(config.granularity, 'fine'); + }); + + test('auto_advance in workflow choices is preserved', () => { + const choices = JSON.stringify({ + mode: 'yolo', + granularity: 'standard', + workflow: { research: true, plan_check: true, verifier: true, nyquist_validation: true, auto_advance: true }, + }); + const result = runGsdTools(['config-new-project', choices], tmpDir); + assert.ok(result.success, `Command failed: ${result.error}`); + + const config = readConfig(tmpDir); + assert.strictEqual(config.workflow.auto_advance, true); + }); + + test('rejects invalid JSON choices', () => { + const result = runGsdTools(['config-new-project', '{not-json}'], tmpDir); + assert.strictEqual(result.success, false); + assert.ok(result.error.includes('Invalid JSON'), `Expected "Invalid JSON" in: ${result.error}`); + }); + + test('output JSON has created:true on success', () => { + const choices = JSON.stringify({ mode: 'interactive', granularity: 'standard' }); + const result = runGsdTools(['config-new-project', choices], tmpDir); + assert.ok(result.success, `Command failed: ${result.error}`); + const out = JSON.parse(result.output); + assert.strictEqual(out.created, true); + assert.strictEqual(out.path, '.planning/config.json'); + }); +}); +``` + +- [ ] **ステップ 1.2: 失敗するテストを実行して失敗を確認する** + +```bash +cd /Users/diego/Dev/get-shit-done +node --test tests/config.test.cjs 2>&1 | grep -E "config-new-project|FAIL|Error" +``` + +期待結果: すべての `config-new-project` テストが "config-new-project is not a valid command" などのエラーで失敗する。 + +- [ ] **ステップ 1.3: config.cjs に `buildNewProjectConfig` と `cmdConfigNewProject` を実装する** + +`get-shit-done/bin/lib/config.cjs` の `validateKnownConfigKeyPath` 関数の後（35行目付近）、`ensureConfigFile` の前に以下を追加する: + +```js +/** + * 新規プロジェクト用の完全展開された設定を構築する。 + * + * 以下の優先順位（昇順）でマージする: + * 1. ハードコードされたデフォルト値 + * 2. ~/.gsd/defaults.json のユーザーレベルデフォルト（存在する場合） + * 3. userChoices（new-project 時にユーザーが明示的に選択した設定） + * + * プレーンオブジェクトを返す — ファイルの書き込みは行わない。 + */ +function buildNewProjectConfig(cwd, userChoices) { + const choices = userChoices || {}; + const homedir = require('os').homedir(); + + // Brave Search API キーの利用可能性を検出 + const braveKeyFile = path.join(homedir, '.gsd', 'brave_api_key'); + const hasBraveSearch = !!(process.env.BRAVE_API_KEY || fs.existsSync(braveKeyFile)); + + // ~/.gsd/defaults.json からユーザーレベルのデフォルトを読み込む（存在する場合） + const globalDefaultsPath = path.join(homedir, '.gsd', 'defaults.json'); + let userDefaults = {}; + try { + if (fs.existsSync(globalDefaultsPath)) { + userDefaults = JSON.parse(fs.readFileSync(globalDefaultsPath, 'utf-8')); + // 非推奨の "depth" キーを "granularity" に移行 + if ('depth' in userDefaults && !('granularity' in userDefaults)) { + const depthToGranularity = { quick: 'coarse', standard: 'standard', comprehensive: 'fine' }; + userDefaults.granularity = depthToGranularity[userDefaults.depth] || userDefaults.depth; + delete userDefaults.depth; + try { + fs.writeFileSync(globalDefaultsPath, JSON.stringify(userDefaults, null, 2), 'utf-8'); + } catch {} + } + } + } catch { + // 不正なグローバルデフォルトは無視 + } + + const hardcoded = { + model_profile: 'balanced', + commit_docs: true, + parallelization: true, + search_gitignored: false, + brave_search: hasBraveSearch, + git: { + branching_strategy: 'none', + phase_branch_template: 'gsd/phase-{phase}-{slug}', + milestone_branch_template: 'gsd/{milestone}-{slug}', + }, + workflow: { + research: true, + plan_check: true, + verifier: true, + nyquist_validation: true, + }, + }; + + // 3段階マージ: hardcoded <- userDefaults <- choices + return { + ...hardcoded, + ...userDefaults, + ...choices, + git: { + ...hardcoded.git, + ...(userDefaults.git || {}), + ...(choices.git || {}), + }, + workflow: { + ...hardcoded.workflow, + ...(userDefaults.workflow || {}), + ...(choices.workflow || {}), + }, + }; +} + +/** + * コマンド: 新規プロジェクト用の完全展開された .planning/config.json を作成する。 + * + * ユーザーが選択した設定を JSON 文字列として受け取る（/gsd-new-project 時に + * ユーザーが明示的に設定したキー）。残りのキーはハードコードされたデフォルトと + * オプションの ~/.gsd/defaults.json から補完される。 + * + * 冪等: config.json が既に存在する場合は { created: false } を返す。 + */ +function cmdConfigNewProject(cwd, choicesJson, raw) { + const configPath = path.join(cwd, '.planning', 'config.json'); + const planningDir = path.join(cwd, '.planning'); + + // 冪等: 既存の設定を上書きしない + if (fs.existsSync(configPath)) { + output({ created: false, reason: 'already_exists' }, raw, 'exists'); + return; + } + + // ユーザーの選択をパース + let userChoices = {}; + if (choicesJson && choicesJson.trim() !== '') { + try { + userChoices = JSON.parse(choicesJson); + } catch (err) { + error('Invalid JSON for config-new-project: ' + err.message); + } + } + + // .planning ディレクトリが存在することを確認 + try { + if (!fs.existsSync(planningDir)) { + fs.mkdirSync(planningDir, { recursive: true }); + } + } catch (err) { + error('Failed to create .planning directory: ' + err.message); + } + + const config = buildNewProjectConfig(cwd, userChoices); + + try { + fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8'); + output({ created: true, path: '.planning/config.json' }, raw, 'created'); + } catch (err) { + error('Failed to write config.json: ' + err.message); + } +} +``` + +また、`config.cjs` の末尾にある `module.exports` に `cmdConfigNewProject` を追加する。 + +- [ ] **ステップ 1.4: テストを実行してパスすることを確認する** + +```bash +cd /Users/diego/Dev/get-shit-done +node --test tests/config.test.cjs 2>&1 | tail -20 +``` + +期待結果: すべての `config-new-project` テストがパスする。既存テストも引き続きパスする。 + +- [ ] **ステップ 1.5: コミット** + +```bash +cd /Users/diego/Dev/get-shit-done +git add get-shit-done/bin/lib/config.cjs tests/config.test.cjs +git commit -m "feat: add config-new-project command for full config materialization" +``` + +--- + +## タスク 2: gsd-tools.cjs に `config-new-project` を登録する + +**ファイル:** + +- 変更: `get-shit-done/bin/gsd-tools.cjs` + +- [ ] **ステップ 2.1: gsd-tools.cjs の switch 文に case を追加する** + +`config-get` の case の後（401行目付近）に以下を追加する: + +```js + case 'config-new-project': { + config.cmdConfigNewProject(cwd, args[1], raw); + break; + } +``` + +また、178行目の usage 文字列を更新して `config-new-project` を含める: + +変更前: `...config-ensure-section, init` +変更後: `...config-ensure-section, config-new-project, init` + +- [ ] **ステップ 2.2: CLI 登録のスモークテスト** + +```bash +cd /Users/diego/Dev/get-shit-done +node get-shit-done/bin/gsd-tools.cjs config-new-project '{"mode":"interactive","granularity":"standard"}' --cwd /tmp/gsd-smoke-$(date +%s) +``` + +期待結果: `{"created":true,"path":".planning/config.json"}` （または類似の出力）が表示される。 + +クリーンアップ: `rm -rf /tmp/gsd-smoke-*` + +- [ ] **ステップ 2.3: フルテストスイートを実行する** + +```bash +cd /Users/diego/Dev/get-shit-done +node --test tests/config.test.cjs 2>&1 | tail -10 +``` + +期待結果: すべてパスする。 + +- [ ] **ステップ 2.4: コミット** + +```bash +cd /Users/diego/Dev/get-shit-done +git add get-shit-done/bin/gsd-tools.cjs +git commit -m "feat: register config-new-project in gsd-tools CLI router" +``` + +--- + +## タスク 3: new-project.md ワークフローを config-new-project を使うように更新する + +**ファイル:** + +- 変更: `get-shit-done/workflows/new-project.md` + +これが中心となる変更。2箇所を更新する必要がある: + +- **ステップ 2a**（自動モードでの設定作成、168〜195行目付近） +- **ステップ 5**（対話モードでの設定作成、470〜498行目付近） + +- [ ] **ステップ 3.1: ステップ 2a（自動モード）を更新する** + +ステップ 2a で config.json を作成しているブロックを探す: + +```markdown +Create `.planning/config.json` with mode set to "yolo": + +```json +{ + "mode": "yolo", + "granularity": "[selected]", + ... +} +``` + +``` + +インライン JSON 書き込みの指示を以下に置き換える: + +```markdown +Create `.planning/config.json` using the CLI (fills in all defaults automatically): + +```bash +mkdir -p .planning +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-new-project "$(cat <<'CHOICES' +{ + "mode": "yolo", + "granularity": "[selected: coarse|standard|fine]", + "parallelization": [true|false], + "commit_docs": [true|false], + "model_profile": "[selected: simple|smart|genius|inherit]", + "workflow": { + "research": [true|false], + "plan_check": [true|false], + "verifier": [true|false], + "nyquist_validation": [true|false], + "auto_advance": true + } +} +CHOICES +)" +``` + +このコマンドはユーザーの選択をすべてのランタイムデフォルト（`search_gitignored`、`brave_search`、`git` セクション）とマージし、完全に展開された設定を生成する。 + +``` + +- [ ] **ステップ 3.2: ステップ 5（対話モード）を更新する** + +ステップ 5 で config.json を作成しているブロックを探す: + +```markdown +Create `.planning/config.json` with all settings: + +```json +{ + "mode": "yolo|interactive", + ... +} +``` + +``` + +以下に置き換える: + +```markdown +Create `.planning/config.json` using the CLI (fills in all defaults automatically): + +```bash +mkdir -p .planning +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-new-project "$(cat <<'CHOICES' +{ + "mode": "[selected: yolo|interactive]", + "granularity": "[selected: coarse|standard|fine]", + "parallelization": [true|false], + "commit_docs": [true|false], + "model_profile": "[selected: simple|smart|genius|inherit]", + "workflow": { + "research": [true|false], + "plan_check": [true|false], + "verifier": [true|false], + "nyquist_validation": [true|false] + } +} +CHOICES +)" +``` + +このコマンドはユーザーの選択をすべてのランタイムデフォルト（`search_gitignored`、`brave_search`、`git` セクション）とマージし、完全に展開された設定を生成する。 + +``` + +- [ ] **ステップ 3.3: ワークフローファイルが正しく読めることを確認する** + +```bash +cd /Users/diego/Dev/get-shit-done +grep -n "config-new-project\|config\.json\|CHOICES" get-shit-done/workflows/new-project.md +``` + +期待結果: `config-new-project` が2箇所（各ステップに1つ）で出現し、設定作成用のインライン JSON テンプレートがなくなっている。 + +- [ ] **ステップ 3.4: コミット** + +```bash +cd /Users/diego/Dev/get-shit-done +git add get-shit-done/workflows/new-project.md +git commit -m "feat: use config-new-project in new-project workflow for full config materialization" +``` + +--- + +## タスク 4: 検証 + +- [ ] **ステップ 4.1: フルテストスイートを実行する** + +```bash +cd /Users/diego/Dev/get-shit-done +node --test tests/ 2>&1 | tail -30 +``` + +期待結果: すべてのテストがパスする（リグレッションなし）。 + +- [ ] **ステップ 4.2: 手動のエンドツーエンド検証** + +`new-project.md` が新規プロジェクトに対して行う処理をシミュレートする: + +```bash +# 新しいプロジェクトディレクトリを作成 +TMP=$(mktemp -d) +cd "$TMP" + +# ステップ 1 のシミュレーション: init new-project の実行結果 +node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs init new-project --cwd "$TMP" + +# ステップ 5 のシミュレーション: 完全な設定を作成 +node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs config-new-project '{ + "mode": "interactive", + "granularity": "standard", + "parallelization": true, + "commit_docs": true, + "model_profile": "balanced", + "workflow": { + "research": true, + "plan_check": true, + "verifier": true, + "nyquist_validation": true + } +}' --cwd "$TMP" + +# ファイルに期待される12個のキーがすべて含まれていることを確認 +echo "=== Generated config.json ===" +cat "$TMP/.planning/config.json" + +# クリーンアップ +rm -rf "$TMP" +``` + +期待される出力: `mode`、`granularity`、`model_profile`、`commit_docs`、`parallelization`、`search_gitignored`、`brave_search`、`git`（サブキー3つ）、`workflow`（サブキー4つ）を含む config.json — トップレベルキーは合計12個（`git` と `workflow` を単一キーとして数える場合は10個）。 + +- [ ] **ステップ 4.3: 冪等性の確認** + +```bash +TMP=$(mktemp -d) +CHOICES='{"mode":"yolo","granularity":"coarse"}' + +node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs config-new-project "$CHOICES" --cwd "$TMP" +FIRST=$(cat "$TMP/.planning/config.json") + +# 2回目の呼び出しは何も変更しないはず +node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs config-new-project "$CHOICES" --cwd "$TMP" +SECOND=$(cat "$TMP/.planning/config.json") + +[ "$FIRST" = "$SECOND" ] && echo "IDEMPOTENT: OK" || echo "IDEMPOTENT: FAIL" +rm -rf "$TMP" +``` + +期待結果: `IDEMPOTENT: OK` + +- [ ] **ステップ 4.4: loadConfig が新しいフォーマットを正しく読み込めることを確認する** + +```bash +TMP=$(mktemp -d) +node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs config-new-project '{ + "mode":"yolo","granularity":"standard","parallelization":true,"commit_docs":true, + "model_profile":"balanced", + "workflow":{"research":true,"plan_check":false,"verifier":true,"nyquist_validation":true} +}' --cwd "$TMP" + +# loadConfig が正しく plan_check（workflow.plan_check としてネスト）を読み取るか +node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs config-get workflow.plan_check --cwd "$TMP" +# 期待値: false + +node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs config-get git.branching_strategy --cwd "$TMP" +# 期待値: "none" + +rm -rf "$TMP" +``` + +- [ ] **ステップ 4.5: 最終フルテストスイート + コミット** + +```bash +cd /Users/diego/Dev/get-shit-done +node --test tests/ 2>&1 | grep -E "pass|fail|error" | tail -5 +``` + +期待結果: すべてパス、失敗0件。 + +--- + +## 付録: アップストリーム向け PR 説明文 + +``` +feat: materialize all config defaults at new-project initialization + +**問題:** +`/gsd-new-project` はオンボーディング時にユーザーが明示的に選択した6つのキーのみで +`.planning/config.json` を作成する。5つの追加キー +（`search_gitignored`、`brave_search`、`git.branching_strategy`、 +`git.phase_branch_template`、`git.milestone_branch_template`）は実行時に +`loadConfig()` が暗黙的に解決するが、ディスクには書き込まれない。 + +これにより2つの問題が生じる: +1. **発見可能性**: ユーザーがソースコードを読まない限り `git.branching_strategy` を + 確認・理解できない — 設定ファイルに表示されない。 +2. **暗黙的な拡張**: `/gsd-settings` や `config-set` が初めて設定に書き込む際にも、 + これらのキーは追加されない。設定ファイルは実効設定のごく一部しか反映しない。 + +**解決策:** +`gsd-tools.cjs` に `config-new-project` CLI コマンドを追加する。このコマンドは: +- ユーザーが選択した値を JSON として受け取る +- すべてのランタイムデフォルト（環境検出される `brave_search` を含む）とマージする +- 完全に展開された設定を一度に書き込む + +`new-project.md` ワークフロー（ステップ 2a と 5）を更新し、ハードコードされた部分的な +JSON テンプレートの書き込みの代わりにこのコマンドを呼び出すようにする。デフォルト値は +`config.cjs` の `buildNewProjectConfig()` という一箇所だけで管理される。 + +**保守的なアプローチである理由:** +- `loadConfig()`、`ensureConfigFile()`、その他の読み取りパスに変更なし +- 新しい設定キーの導入なし +- セマンティクスの変更なし — システムが既に暗黙的に解決していたのと同じ値 +- 完全な後方互換性: `loadConfig()` は古い部分的フォーマット（既存プロジェクト）と + 新しい完全フォーマットの両方を引き続き処理可能 +- 冪等: `config-new-project` を2回呼んでも安全 +- 新しいユーザー向けフラグなし + +**発見可能性が向上する理由:** +初めて `.planning/config.json` を開いた開発者が `git.branching_strategy: "none"` を +見て、GSD のソースコードを読まなくてもブランチ戦略機能が利用可能で設定変更できることを +即座に理解できるようになる。 +``` diff --git a/gsd-opencode/docs/ja-JP/superpowers/specs/2026-03-20-multi-project-workspaces-design.md b/gsd-opencode/docs/ja-JP/superpowers/specs/2026-03-20-multi-project-workspaces-design.md new file mode 100644 index 0000000..da7ad2e --- /dev/null +++ b/gsd-opencode/docs/ja-JP/superpowers/specs/2026-03-20-multi-project-workspaces-design.md @@ -0,0 +1,185 @@ +# マルチプロジェクトワークスペース (`/gsd-new-workspace`) + +**Issue:** #1241 +**Date:** 2026-03-20 +**Status:** Approved + +## 課題 + +GSD は作業ディレクトリごとに1つの `.planning/` ディレクトリに紐づいています。複数の独立したプロジェクトを持つユーザー（20以上の子リポジトリを含むモノレポ構成など）や、同一リポジトリ内でフィーチャーブランチの分離が必要なユーザーは、手動でのクローンや状態管理なしに並行して GSD セッションを実行することができません。 + +## 解決策 + +3つの新しいコマンドで**物理的なワークスペースディレクトリ**を作成・一覧表示・削除します。各ワークスペースにはリポジトリのコピー（git worktree またはクローン）と独立した `.planning/` ディレクトリが含まれます。 + +これにより2つのユースケースに対応します： +- **マルチリポジトリオーケストレーション (A):** 親ディレクトリから複数のリポジトリにまたがるワークスペース +- **フィーチャーブランチの分離 (B):** 現在のリポジトリの worktree を含むワークスペース（`--repos .` を使用した A の特殊ケース） + +## コマンド + +### `/gsd-new-workspace` + +リポジトリのコピーと独自の `.planning/` を持つワークスペースディレクトリを作成します。 + +``` +/gsd-new-workspace --name feature-b --repos hr-ui,ZeymoAPI --path ~/workspaces/feature-b +/gsd-new-workspace --name feature-b --repos . --strategy worktree # same-repo isolation +``` + +**引数:** + +| フラグ | 必須 | デフォルト | 説明 | +|------|----------|---------|-------------| +| `--name` | はい | — | ワークスペース名 | +| `--repos` | いいえ | 対話的な選択 | カンマ区切りのリポジトリパスまたは名前 | +| `--path` | いいえ | `~/gsd-workspaces/` | 出力先ディレクトリ | +| `--strategy` | いいえ | `worktree` | `worktree`（軽量、.git を共有）または `clone`（完全に独立） | +| `--branch` | いいえ | `workspace/` | チェックアウトするブランチ | +| `--auto` | いいえ | false | 対話的な質問をスキップし、デフォルト値を使用 | + +### `/gsd-list-workspaces` + +`~/gsd-workspaces/*/WORKSPACE.md` をスキャンしてワークスペースマニフェストを検索します。名前、パス、リポジトリ数、GSD ステータス（PROJECT.md の有無、現在のフェーズ）をテーブル形式で表示します。 + +### `/gsd-remove-workspace` + +確認後にワークスペースディレクトリを削除します。worktree 戦略の場合、まず各メンバーリポジトリに対して `git worktree remove` を実行します。コミットされていない変更があるリポジトリがある場合は削除を拒否します。 + +## ディレクトリ構造 + +``` +~/gsd-workspaces/feature-b/ # workspace root +├── WORKSPACE.md # manifest +├── .planning/ # independent GSD planning directory +│ ├── PROJECT.md # (if user ran /gsd-new-project) +│ ├── STATE.md +│ └── config.json +├── hr-ui/ # git worktree of source repo +│ └── (repo contents on workspace/feature-b branch) +└── ZeymoAPI/ # git worktree of source repo + └── (repo contents on workspace/feature-b branch) +``` + +主要な特性： +- `.planning/` はワークスペースのルートに配置され、個々のリポジトリ内には配置されない +- 各リポジトリはワークスペースルート直下の対等なディレクトリ +- `WORKSPACE.md` はルートにある唯一の GSD 固有ファイル（`.planning/` を除く） +- `--strategy clone` の場合も同じ構造だが、リポジトリは完全なクローンとなる + +## WORKSPACE.md のフォーマット + +```markdown +# Workspace: feature-b + +Created: 2026-03-20 +Strategy: worktree + +## Member Repos + +| Repo | Source | Branch | Strategy | +|------|--------|--------|----------| +| hr-ui | /root/source/repos/hr-ui | workspace/feature-b | worktree | +| ZeymoAPI | /root/source/repos/ZeymoAPI | workspace/feature-b | worktree | + +## Notes + +[User can add context about what this workspace is for] +``` + +## ワークフロー + +### `/gsd-new-workspace` のワークフロー手順 + +1. **セットアップ** — `init new-workspace` を呼び出し、JSON コンテキストを解析する +2. **入力の収集** — `--name`/`--repos`/`--path` が指定されていない場合、対話的に質問する。リポジトリの選択時は、カレントディレクトリ内の子 `.git` ディレクトリを選択肢として表示する +3. **バリデーション** — 出力先パスが存在しない（または空である）こと。ソースリポジトリが存在し、git リポジトリであることを確認する +4. **ワークスペースディレクトリの作成** — `mkdir -p ` +5. **リポジトリのコピー** — 各リポジトリについて： + - Worktree: `git worktree add / -b workspace/` + - Clone: `git clone /` +6. **WORKSPACE.md の書き込み** — ソースパス、戦略、ブランチを含むマニフェスト +7. **.planning/ の初期化** — `mkdir -p /.planning` +8. **/gsd-new-project の提案** — 新しいワークスペースでプロジェクト初期化を実行するか確認する +9. **コミット** — commit_docs が有効な場合、WORKSPACE.md のアトミックコミット +10. **完了** — ワークスペースのパスと次のステップを表示する + +### Init 関数 (`cmdInitNewWorkspace`) + +検出項目： +- カレントディレクトリ内の子 git リポジトリ（対話的なリポジトリ選択用） +- 出力先パスが既に存在するかどうか +- ソースリポジトリにコミットされていない変更があるかどうか +- `git worktree` が利用可能かどうか +- デフォルトのワークスペースベースディレクトリ (`~/gsd-workspaces/`) + +ワークフローの分岐制御用フラグを含む JSON を返します。 + +## エラーハンドリング + +### バリデーションエラー（作成をブロック） + +- **出力先パスが存在し、空でない場合** — 別の名前/パスを選択するよう提案するエラー +- **ソースリポジトリのパスが存在しない、または git リポジトリでない場合** — 失敗したリポジトリを一覧表示するエラー +- **`git worktree add` が失敗した場合**（例：ブランチが既に存在する） — `workspace/-` ブランチにフォールバックし、それも失敗した場合はエラー + +### グレースフルハンドリング + +- **ソースリポジトリにコミットされていない変更がある場合** — 警告するが許可する（worktree はブランチを新規にチェックアウトし、作業ディレクトリの状態はコピーしない） +- **マルチリポジトリワークスペースでの部分的な失敗** — 成功したリポジトリでワークスペースを作成し、失敗を報告し、部分的な WORKSPACE.md を書き込む +- **`--repos .`（現在のリポジトリ、ケース B）** — ディレクトリ名または git remote からリポジトリ名を検出し、サブディレクトリ名として使用する + +### Remove-Workspace の安全性 + +- **ワークスペース内のリポジトリにコミットされていない変更がある場合** — 削除を拒否し、変更のあるリポジトリを表示する +- **Worktree の削除が失敗した場合**（例：ソースリポジトリが削除されている） — 警告し、ディレクトリのクリーンアップを続行する +- **確認** — ワークスペース名を入力する明示的な確認を要求する + +### List-Workspaces のエッジケース + +- **`~/gsd-workspaces/` が存在しない場合** — 「ワークスペースが見つかりません」 +- **WORKSPACE.md は存在するが、内部のリポジトリがなくなっている場合** — ワークスペースを表示し、リポジトリを欠落としてマークする + +## テスト + +### ユニットテスト (`tests/workspace.test.cjs`) + +1. `cmdInitNewWorkspace` が正しい JSON を返す — 子 git リポジトリの検出、出力先パスのバリデーション、git worktree の利用可能性の検出 +2. WORKSPACE.md の生成 — リポジトリテーブル、戦略、日付を含む正しいフォーマット +3. リポジトリの検出 — カレントディレクトリの子要素内の `.git` ディレクトリを識別し、git 以外のディレクトリやファイルをスキップする +4. バリデーション — 既存の空でない出力先パスを拒否し、git リポジトリでないソースパスを拒否する + +### 統合テスト（同一ファイル） + +5. Worktree の作成 — ワークスペースを作成し、リポジトリディレクトリが有効な git worktree であることを検証する +6. クローンの作成 — ワークスペースを作成し、リポジトリが独立したクローンであることを検証する +7. ワークスペースの一覧表示 — 2つのワークスペースを作成し、一覧出力に両方が含まれることを検証する +8. ワークスペースの削除 — worktree でワークスペースを作成し、削除してクリーンアップを検証する +9. 部分的な失敗 — 有効なリポジトリ1つと無効なパス1つで、有効なリポジトリのみでワークスペースが作成されることを検証する + +すべてのテストは一時ディレクトリを使用し、終了時にクリーンアップします。既存の `node:test` + `node:assert` パターンに従います。 + +## 実装ファイル + +| コンポーネント | パス | +|-----------|------| +| コマンド: new-workspace | `commands/gsd/new-workspace.md` | +| コマンド: list-workspaces | `commands/gsd/list-workspaces.md` | +| コマンド: remove-workspace | `commands/gsd/remove-workspace.md` | +| ワークフロー: new-workspace | `get-shit-done/workflows/new-workspace.md` | +| ワークフロー: list-workspaces | `get-shit-done/workflows/list-workspaces.md` | +| ワークフロー: remove-workspace | `get-shit-done/workflows/remove-workspace.md` | +| Init 関数 | `get-shit-done/bin/lib/init.cjs`（`cmdInitNewWorkspace`、`cmdInitListWorkspaces`、`cmdInitRemoveWorkspace` を追加） | +| ルーティング | `get-shit-done/bin/gsd-tools.cjs`（init switch にケースを追加） | +| テスト | `tests/workspace.test.cjs` | + +## 設計上の決定 + +| 決定事項 | 根拠 | +|----------|-----------| +| 論理的なレジストリではなく物理ディレクトリを採用 | ファイルシステムを信頼の源とする — GSD の既存の cwd ベースの検出パターンと一致する | +| Worktree をデフォルト戦略とする | 軽量（.git オブジェクトを共有）、作成が高速、クリーンアップが容易 | +| `.planning/` をワークスペースルートに配置 | 個々のリポジトリの planning から完全に分離できる。各ワークスペースは独立した GSD プロジェクトとなる | +| 中央レジストリを使用しない | 状態の乖離を回避する。`list-workspaces` はファイルシステムを直接スキャンする | +| ケース B を A の特殊ケースとする | `--repos .` で同じ仕組みを再利用し、フィーチャーブランチ専用のコードが不要 | +| デフォルトパスを `~/gsd-workspaces/` とする | `list-workspaces` がスキャンしやすい予測可能な場所に配置し、ワークスペースをソースリポジトリの外に保つ | diff --git a/gsd-opencode/docs/ja-JP/workflow-discuss-mode.md b/gsd-opencode/docs/ja-JP/workflow-discuss-mode.md new file mode 100644 index 0000000..9c7760e --- /dev/null +++ b/gsd-opencode/docs/ja-JP/workflow-discuss-mode.md @@ -0,0 +1,65 @@ +# ディスカスモード: Assumptions vs Interview + +GSD の discuss フェーズには、プランニング前に実装コンテキストを収集するための2つのモードがあります。 + +## モード + +### `discuss`（デフォルト） + +従来のインタビュー形式のフローです。OpenCode がフェーズ内の不明瞭な領域を特定し、選択肢として提示した後、各領域について約4つの質問を行います。以下のケースに適しています: + +- コードベースが初めてで、初期フェーズの場合 +- ユーザーが積極的に意見を表明したい場合 +- ガイド付きの対話的なコンテキスト収集を好むユーザー + +### `assumptions` + +コードベース優先のフローです。OpenCode がサブエージェントを通じてコードベースを深く分析し（関連ファイルを5〜15個読み取り）、根拠付きの仮説を立てて確認・修正を求めます。以下のケースに適しています: + +- 明確なパターンが確立されたコードベース +- インタビューの質問が自明と感じるユーザー +- より高速なコンテキスト収集（約2〜4回のやり取り vs 約15〜20回） + +## 設定 + +```bash +# assumptions モードを有効にする +gsd-tools config-set workflow.discuss_mode assumptions + +# interview モードに戻す +gsd-tools config-set workflow.discuss_mode discuss +``` + +この設定はプロジェクト単位です（`.planning/config.json` に保存されます）。 + +## Assumptions モードの仕組み + +1. **初期化** — discuss モードと同様（前回のコンテキスト読み込み、コードベース調査、TODO チェック） +2. **深層分析** — Explore サブエージェントがフェーズに関連するコードベースファイルを5〜15個読み取る +3. **仮説の提示** — 各仮説には以下が含まれる: + - OpenCode が何をどのような理由で行うか（ファイルパスを引用） + - 仮説が間違っていた場合のリスク + - 確信度レベル（Confident / Likely / Unclear） +4. **確認または修正** — ユーザーが仮説をレビューし、変更が必要なものを選択 +5. **CONTEXT.md の生成** — discuss モードと同一の出力フォーマット + +## フラグの互換性 + +| フラグ | `discuss` モード | `assumptions` モード | +|--------|-----------------|---------------------| +| `--auto` | 推奨回答を自動選択 | 確認ゲートをスキップし、Unclear 項目を自動解決 | +| `--batch` | 質問をバッチでグループ化 | N/A（修正は既にバッチ化済み） | +| `--text` | プレーンテキスト形式の質問（リモートセッション向け） | プレーンテキスト形式の質問（リモートセッション向け） | +| `--analyze` | 質問ごとにトレードオフ表を表示 | N/A（仮説に根拠が含まれる） | + +## 出力 + +両モードとも、同じ6セクション構成の CONTEXT.md を生成します: +- `` — フェーズの境界 +- `` — 確定した実装上の決定事項 +- `` — 下流エージェントが読むべき仕様・ドキュメント +- `` — 再利用可能なアセット、パターン、統合ポイント +- `` — ユーザーの参照情報と好み +- `` — 将来のフェーズに先送りするアイデア + +下流エージェント（researcher、planner、checker）は、モードに関係なくこの出力を同一に消費します。 diff --git a/gsd-opencode/docs/ko-KR/AGENTS.md b/gsd-opencode/docs/ko-KR/AGENTS.md new file mode 100644 index 0000000..a614a30 --- /dev/null +++ b/gsd-opencode/docs/ko-KR/AGENTS.md @@ -0,0 +1,428 @@ +# GSD 에이전트 레퍼런스 + +> 18개의 전문화된 에이전트 — 역할, 도구, 생성 패턴, 관계를 모두 포함합니다. 아키텍처 맥락은 [Architecture](ARCHITECTURE.md)를 참조하세요. + +--- + +## 개요 + +GSD는 멀티 에이전트 아키텍처를 사용합니다. 가벼운 오케스트레이터(워크플로우 파일)가 전문화된 에이전트를 새로운 컨텍스트 윈도우로 생성합니다. 각 에이전트는 집중된 역할, 제한된 도구 접근 권한을 가지며 특정 결과물을 생성합니다. + +### 에이전트 카테고리 + +| 카테고리 | 수 | 에이전트 | +|----------|-------|--------| +| Researchers | 3 | project-researcher, phase-researcher, ui-researcher | +| Analyzers | 2 | assumptions-analyzer, advisor-researcher | +| Synthesizers | 1 | research-synthesizer | +| Planners | 1 | planner | +| Roadmappers | 1 | roadmapper | +| Executors | 1 | executor | +| Checkers | 3 | plan-checker, integration-checker, ui-checker | +| Verifiers | 1 | verifier | +| Auditors | 2 | nyquist-auditor, ui-auditor | +| Mappers | 1 | codebase-mapper | +| Debuggers | 1 | debugger | + +--- + +## 에이전트 상세 + +### gsd-project-researcher + +**역할:** 로드맵 생성 전에 도메인 생태계를 조사합니다. + +| 속성 | 값 | +|----------|-------| +| **생성 주체** | `/gsd-new-project`, `/gsd-new-milestone` | +| **병렬성** | 4개 인스턴스 (stack, features, architecture, pitfalls) | +| **도구** | read, write, bash, grep, glob, websearch, webfetch, mcp (context7) | +| **모델 (balanced)** | Sonnet | +| **생성물** | `.planning/research/STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md` | + +**기능.** +- 최신 생태계 정보를 위한 웹 검색 +- 라이브러리 문서를 위한 Context7 MCP 통합 +- 조사 문서를 디스크에 직접 작성 (오케스트레이터 컨텍스트 부하 감소) + +--- + +### gsd-phase-researcher + +**역할:** 계획 수립 전에 특정 단계의 구현 방법을 조사합니다. + +| 속성 | 값 | +|----------|-------| +| **생성 주체** | `/gsd-plan-phase` | +| **병렬성** | 4개 인스턴스 (project-researcher와 동일한 집중 영역) | +| **도구** | read, write, bash, grep, glob, websearch, webfetch, mcp (context7) | +| **모델 (balanced)** | Sonnet | +| **생성물** | `{phase}-RESEARCH.md` | + +**기능.** +- CONTEXT.md를 읽어 사용자 결정에 맞게 조사 방향을 설정합니다 +- 특정 단계 도메인의 구현 패턴을 조사합니다 +- Nyquist 검증 매핑을 위한 테스트 인프라를 감지합니다 + +--- + +### gsd-ui-researcher + +**역할:** 프론트엔드 단계를 위한 UI 디자인 계약서를 생성합니다. + +| 속성 | 값 | +|----------|-------| +| **생성 주체** | `/gsd-ui-phase` | +| **병렬성** | 단일 인스턴스 | +| **도구** | read, write, bash, grep, glob, websearch, webfetch, mcp (context7) | +| **모델 (balanced)** | Sonnet | +| **색상** | `#E879F9` (fuchsia) | +| **생성물** | `{phase}-UI-SPEC.md` | + +**기능.** +- 디자인 시스템 상태 감지 (shadcn components.json, Tailwind config, 기존 토큰) +- React/Next.js/Vite 프로젝트를 위한 shadcn 초기화 제안 +- 아직 답변되지 않은 디자인 계약 질문만 질의합니다 +- 서드파티 컴포넌트에 대한 레지스트리 안전 게이트를 적용합니다 + +--- + +### gsd-assumptions-analyzer + +**역할:** 단계에 대한 코드베이스를 심층 분석하고 증거, 신뢰 수준, 오류 시 결과를 포함한 구조화된 가정을 반환합니다. + +| 속성 | 값 | +|----------|-------| +| **생성 주체** | `discuss-phase-assumptions` 워크플로우 (`workflow.discuss_mode = 'assumptions'`인 경우) | +| **병렬성** | 단일 인스턴스 | +| **도구** | read, bash, grep, glob | +| **모델 (balanced)** | Sonnet | +| **색상** | Cyan | +| **생성물** | 결정문, 증거 파일 경로, 신뢰 수준을 포함한 구조화된 가정 | + +**핵심 동작.** +- ROADMAP.md 단계 설명과 이전 CONTEXT.md 파일을 읽습니다 +- 단계 관련 파일(컴포넌트, 패턴, 유사 기능)을 코드베이스에서 검색합니다 +- 증거 기반 가정 형성을 위해 가장 관련성 높은 소스 파일 5~15개를 읽습니다 +- 신뢰 수준을 분류합니다. Confident(코드에서 명확), Likely(합리적 추론), Unclear(여러 방향 가능) +- 외부 조사가 필요한 항목을 표시합니다 (라이브러리 호환성, 생태계 모범 사례) +- 티어에 따라 출력을 조정합니다. full_maturity(3~5개 영역), standard(3~4개), minimal_decisive(2~3개) + +--- + +### gsd-advisor-researcher + +**역할:** discuss-phase 어드바이저 모드에서 단일 회색 지대 결정을 조사하고 구조화된 비교 표를 반환합니다. + +| 속성 | 값 | +|----------|-------| +| **생성 주체** | `discuss-phase` 워크플로우 (ADVISOR_MODE = true인 경우) | +| **병렬성** | 복수 인스턴스 (회색 지대당 하나) | +| **도구** | read, bash, grep, glob, websearch, webfetch, mcp (context7) | +| **모델 (balanced)** | Sonnet | +| **색상** | Cyan | +| **생성물** | 5열 비교 표 (Option / Pros / Cons / Complexity / Recommendation)와 근거 단락 | + +**핵심 동작.** +- OpenCode의 지식, Context7, 웹 검색을 사용하여 할당된 단일 회색 지대를 조사합니다 +- 실질적으로 실행 가능한 옵션만 제시합니다 — 형식적인 대안은 포함하지 않습니다 +- Complexity 열은 영향 범위와 위험을 사용합니다 (시간 추정치는 사용하지 않음) +- 권장 사항은 조건부로 제시합니다 ("Rec if X", "Rec if Y") — 단일 승자 순위는 없습니다 +- 티어에 따라 출력을 조정합니다. full_maturity(성숙도 신호 포함 3~5개 옵션), standard(2~4개), minimal_decisive(2개 옵션, 결정적 권장 사항) + +--- + +### gsd-research-synthesizer + +**역할:** 병렬 조사자들의 출력을 통합된 요약으로 합칩니다. + +| 속성 | 값 | +|----------|-------| +| **생성 주체** | `/gsd-new-project` (4개 조사자 완료 후) | +| **병렬성** | 단일 인스턴스 (조사자 이후 순차적) | +| **도구** | read, write, bash | +| **모델 (balanced)** | Sonnet | +| **색상** | Purple | +| **생성물** | `.planning/research/SUMMARY.md` | + +--- + +### gsd-planner + +**역할:** 작업 분류, 의존성 분석, 목표 역방향 검증을 포함한 실행 가능한 단계 계획을 생성합니다. + +| 속성 | 값 | +|----------|-------| +| **생성 주체** | `/gsd-plan-phase`, `/gsd-quick` | +| **병렬성** | 단일 인스턴스 | +| **도구** | read, write, bash, glob, grep, webfetch, mcp (context7) | +| **모델 (balanced)** | Opus | +| **색상** | Green | +| **생성물** | `{phase}-{N}-PLAN.md` 파일 | + +**핵심 동작.** +- PROJECT.md, REQUIREMENTS.md, CONTEXT.md, RESEARCH.md를 읽습니다 +- 단일 컨텍스트 윈도우에 맞는 크기의 2~3개 원자적 작업 계획을 생성합니다 +- `` 요소를 포함한 XML 구조를 사용합니다 +- `read_first`와 `acceptance_criteria` 섹션을 포함합니다 +- 계획을 의존성 웨이브로 그룹화합니다 + +--- + +### gsd-roadmapper + +**역할:** 단계 분류 및 요구 사항 매핑을 포함한 프로젝트 로드맵을 생성합니다. + +| 속성 | 값 | +|----------|-------| +| **생성 주체** | `/gsd-new-project` | +| **병렬성** | 단일 인스턴스 | +| **도구** | read, write, bash, glob, grep | +| **모델 (balanced)** | Sonnet | +| **색상** | Purple | +| **생성물** | `ROADMAP.md` | + +**핵심 동작.** +- 요구 사항을 단계에 매핑합니다 (추적성) +- 요구 사항으로부터 성공 기준을 도출합니다 +- 단계 수에 대한 세분화 설정을 준수합니다 +- 커버리지를 검증합니다 (모든 v1 요구 사항이 단계에 매핑됨) + +--- + +### gsd-executor + +**역할:** 원자적 커밋, 이탈 처리, 체크포인트 프로토콜로 GSD 계획을 실행합니다. + +| 속성 | 값 | +|----------|-------| +| **생성 주체** | `/gsd-execute-phase`, `/gsd-quick` | +| **병렬성** | 복수 (웨이브 내 병렬, 웨이브 간 순차적) | +| **도구** | read, write, edit, bash, grep, glob | +| **모델 (balanced)** | Sonnet | +| **색상** | Yellow | +| **생성물** | 코드 변경사항, git 커밋, `{phase}-{N}-SUMMARY.md` | + +**핵심 동작.** +- 계획당 새로운 200K 컨텍스트 윈도우를 사용합니다 +- XML 작업 지시를 정확히 따릅니다 +- 완료된 작업마다 원자적 git 커밋을 수행합니다 +- 체크포인트 유형을 처리합니다. auto, human-verify, decision, human-action +- SUMMARY.md에 계획 이탈을 보고합니다 +- 검증 실패 시 노드 복구를 실행합니다 + +--- + +### gsd-plan-checker + +**역할:** 실행 전에 계획이 단계 목표를 달성할 수 있는지 검증합니다. + +| 속성 | 값 | +|----------|-------| +| **생성 주체** | `/gsd-plan-phase` (검증 루프, 최대 3회 반복) | +| **병렬성** | 단일 인스턴스 (반복적) | +| **도구** | read, bash, glob, grep | +| **모델 (balanced)** | Sonnet | +| **색상** | Green | +| **생성물** | 구체적인 피드백을 포함한 PASS/FAIL 판정 | + +**8가지 검증 차원.** +1. 요구 사항 커버리지 +2. 작업 원자성 +3. 의존성 순서 +4. 파일 범위 +5. 검증 명령어 +6. 컨텍스트 적합성 +7. 누락 감지 +8. Nyquist 준수 (활성화된 경우) + +--- + +### gsd-integration-checker + +**역할:** 단계 간 통합 및 엔드투엔드 흐름을 검증합니다. + +| 속성 | 값 | +|----------|-------| +| **생성 주체** | `/gsd-audit-milestone` | +| **병렬성** | 단일 인스턴스 | +| **도구** | read, bash, grep, glob | +| **모델 (balanced)** | Sonnet | +| **색상** | Blue | +| **생성물** | 통합 검증 보고서 | + +--- + +### gsd-ui-checker + +**역할:** 품질 차원에 대해 UI-SPEC.md 디자인 계약서를 검증합니다. + +| 속성 | 값 | +|----------|-------| +| **생성 주체** | `/gsd-ui-phase` (검증 루프, 최대 2회 반복) | +| **병렬성** | 단일 인스턴스 | +| **도구** | read, bash, glob, grep | +| **모델 (balanced)** | Sonnet | +| **색상** | `#22D3EE` (cyan) | +| **생성물** | BLOCK/FLAG/PASS 판정 | + +--- + +### gsd-verifier + +**역할:** 목표 역방향 분석을 통해 단계 목표 달성 여부를 검증합니다. + +| 속성 | 값 | +|----------|-------| +| **생성 주체** | `/gsd-execute-phase` (모든 executor 완료 후) | +| **병렬성** | 단일 인스턴스 | +| **도구** | read, write, bash, grep, glob | +| **모델 (balanced)** | Sonnet | +| **색상** | Green | +| **생성물** | `{phase}-VERIFICATION.md` | + +**핵심 동작.** +- 작업 완료 여부가 아닌 단계 목표에 대해 코드베이스를 확인합니다 +- 구체적인 증거를 포함한 PASS/FAIL 결과를 제공합니다 +- `/gsd-verify-work`가 처리할 문제를 기록합니다 + +--- + +### gsd-nyquist-auditor + +**역할:** 테스트를 생성하여 Nyquist 검증 누락을 채웁니다. + +| 속성 | 값 | +|----------|-------| +| **생성 주체** | `/gsd-validate-phase` | +| **병렬성** | 단일 인스턴스 | +| **도구** | read, write, edit, bash, grep, glob | +| **모델 (balanced)** | Sonnet | +| **생성물** | 테스트 파일, 업데이트된 `VALIDATION.md` | + +**핵심 동작.** +- 구현 코드는 절대 수정하지 않습니다 — 테스트 파일만 수정합니다 +- 누락당 최대 3번 시도합니다 +- 구현 버그는 사용자에게 에스컬레이션으로 표시합니다 + +--- + +### gsd-ui-auditor + +**역할:** 구현된 프론트엔드 코드에 대한 사후 6기둥 시각적 감사를 수행합니다. + +| 속성 | 값 | +|----------|-------| +| **생성 주체** | `/gsd-ui-review` | +| **병렬성** | 단일 인스턴스 | +| **도구** | read, write, bash, grep, glob | +| **모델 (balanced)** | Sonnet | +| **색상** | `#F472B6` (pink) | +| **생성물** | 점수를 포함한 `{phase}-UI-REVIEW.md` | + +**6가지 감사 기둥 (1-4점 채점).** +1. 카피라이팅 +2. 시각적 요소 +3. 색상 +4. 타이포그래피 +5. 간격 +6. 경험 디자인 + +--- + +### gsd-codebase-mapper + +**역할:** 코드베이스를 탐색하고 구조화된 분석 문서를 작성합니다. + +| 속성 | 값 | +|----------|-------| +| **생성 주체** | `/gsd-map-codebase` | +| **병렬성** | 4개 인스턴스 (tech, architecture, quality, concerns) | +| **도구** | read, bash, grep, glob, write | +| **모델 (balanced)** | Haiku | +| **색상** | Cyan | +| **생성물** | `.planning/codebase/*.md` (7개 문서) | + +**핵심 동작.** +- 읽기 전용 탐색과 구조화된 출력 +- 문서를 디스크에 직접 작성합니다 +- 추론 불필요 — 파일 내용에서 패턴 추출 + +--- + +### gsd-debugger + +**역할:** 영구 상태를 활용한 과학적 방법으로 버그를 조사합니다. + +| 속성 | 값 | +|----------|-------| +| **생성 주체** | `/gsd-debug`, `/gsd-verify-work` (실패 시) | +| **병렬성** | 단일 인스턴스 (대화형) | +| **도구** | read, write, edit, bash, grep, glob, websearch | +| **모델 (balanced)** | Sonnet | +| **색상** | Orange | +| **생성물** | `.planning/debug/*.md`, 지식 베이스 업데이트 | + +**디버그 세션 생명주기.** +`gathering` → `investigating` → `fixing` → `verifying` → `awaiting_human_verify` → `resolved` + +**핵심 동작.** +- 가설, 증거, 제거된 이론을 추적합니다 +- 컨텍스트 초기화 이후에도 상태가 유지됩니다 +- 해결됨으로 표시하기 전에 사람의 검증이 필요합니다 +- 해결 시 영구 지식 베이스에 추가합니다 +- 새 세션 시작 시 지식 베이스를 참조합니다 + +--- + +### gsd-user-profiler + +**역할:** 8가지 행동 차원에 걸쳐 세션 메시지를 분석하여 점수화된 개발자 프로필을 생성합니다. + +| 속성 | 값 | +|----------|-------| +| **생성 주체** | `/gsd-profile-user` | +| **병렬성** | 단일 인스턴스 | +| **도구** | read | +| **모델 (balanced)** | Sonnet | +| **색상** | Magenta | +| **생성물** | `USER-PROFILE.md`, `/gsd-dev-preferences`, `AGENTS.md` 프로필 섹션 | + +**행동 차원.** +커뮤니케이션 스타일, 결정 패턴, 디버깅 접근 방식, UX 선호도, 벤더 선택, 불만 요인, 학습 스타일, 설명 깊이. + +**핵심 동작.** +- 읽기 전용 에이전트 — 추출된 세션 데이터를 분석하며 파일을 수정하지 않습니다 +- 신뢰 수준과 증거 인용을 포함한 점수화된 차원을 생성합니다 +- 세션 기록이 없는 경우 설문지 대체 방식을 사용합니다 + +--- + +## 에이전트 도구 권한 요약 + +| 에이전트 | read | write | edit | bash | grep | glob | websearch | webfetch | MCP | +|-------|------|-------|------|------|------|------|-----------|----------|-----| +| project-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| phase-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| ui-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| assumptions-analyzer | ✓ | | | ✓ | ✓ | ✓ | | | | +| advisor-researcher | ✓ | | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| research-synthesizer | ✓ | ✓ | | ✓ | | | | | | +| planner | ✓ | ✓ | | ✓ | ✓ | ✓ | | ✓ | ✓ | +| roadmapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | | +| executor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | | +| plan-checker | ✓ | | | ✓ | ✓ | ✓ | | | | +| integration-checker | ✓ | | | ✓ | ✓ | ✓ | | | | +| ui-checker | ✓ | | | ✓ | ✓ | ✓ | | | | +| verifier | ✓ | ✓ | | ✓ | ✓ | ✓ | | | | +| nyquist-auditor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | | +| ui-auditor | ✓ | ✓ | | ✓ | ✓ | ✓ | | | | +| codebase-mapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | | +| debugger | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | +| user-profiler | ✓ | | | | | | | | | + +**최소 권한 원칙.** +- Checker는 읽기 전용입니다 (write/edit 없음) — 평가만 하며 수정하지 않습니다 +- Researcher는 웹 접근 권한을 가집니다 — 최신 생태계 정보가 필요하기 때문입니다 +- Executor는 edit 권한을 가집니다 — 코드를 수정하지만 웹 접근은 없습니다 +- Mapper는 write 권한을 가집니다 — 분석 문서를 작성하지만 edit은 없습니다 (코드 변경 없음) diff --git a/gsd-opencode/docs/ko-KR/ARCHITECTURE.md b/gsd-opencode/docs/ko-KR/ARCHITECTURE.md new file mode 100644 index 0000000..4f09879 --- /dev/null +++ b/gsd-opencode/docs/ko-KR/ARCHITECTURE.md @@ -0,0 +1,527 @@ +# GSD 아키텍처 + +> 기여자와 고급 사용자를 위한 시스템 아키텍처입니다. 사용자 문서는 [Feature Reference](FEATURES.md) 또는 [User Guide](USER-GUIDE.md)를 참조하세요. + +--- + +## 목차 + +- [시스템 개요](#system-overview) +- [설계 원칙](#design-principles) +- [컴포넌트 아키텍처](#component-architecture) +- [에이전트 모델](#agent-model) +- [데이터 흐름](#data-flow) +- [파일 시스템 구조](#file-system-layout) +- [인스톨러 아키텍처](#installer-architecture) +- [훅 시스템](#hook-system) +- [CLI 도구 레이어](#cli-tools-layer) +- [런타임 추상화](#runtime-abstraction) + +--- + +## 시스템 개요 + +GSD는 사용자와 AI 코딩 에이전트(OpenCode, Gemini CLI, OpenCode, Codex, Copilot, Antigravity) 사이에 위치하는 **메타 프롬프팅 프레임워크**입니다. 다음을 제공합니다. + +1. **컨텍스트 엔지니어링** — 작업별로 AI에게 필요한 모든 것을 제공하는 구조화된 아티팩트 +2. **멀티 에이전트 오케스트레이션** — 새로운 컨텍스트 윈도우로 전문화된 에이전트를 생성하는 가벼운 오케스트레이터 +3. **명세 주도 개발** — 요구 사항 → 조사 → 계획 → 실행 → 검증 파이프라인 +4. **상태 관리** — 세션과 컨텍스트 초기화를 넘나드는 영구적인 프로젝트 메모리 + +``` +┌──────────────────────────────────────────────────────┐ +│ USER │ +│ /gsd-command [args] │ +└─────────────────────┬────────────────────────────────┘ + │ +┌─────────────────────▼────────────────────────────────┐ +│ COMMAND LAYER │ +│ commands/gsd/*.md — Prompt-based command files │ +│ (OpenCode custom commands / Codex skills) │ +└─────────────────────┬────────────────────────────────┘ + │ +┌─────────────────────▼────────────────────────────────┐ +│ WORKFLOW LAYER │ +│ get-shit-done/workflows/*.md — Orchestration logic │ +│ (Reads references, spawns agents, manages state) │ +└──────┬──────────────┬─────────────────┬──────────────┘ + │ │ │ +┌──────▼──────┐ ┌─────▼─────┐ ┌────────▼───────┐ +│ AGENT │ │ AGENT │ │ AGENT │ +│ (fresh │ │ (fresh │ │ (fresh │ +│ context) │ │ context)│ │ context) │ +└──────┬──────┘ └─────┬─────┘ └────────┬───────┘ + │ │ │ +┌──────▼──────────────▼─────────────────▼──────────────┐ +│ CLI TOOLS LAYER │ +│ get-shit-done/bin/gsd-tools.cjs │ +│ (State, config, phase, roadmap, verify, templates) │ +└──────────────────────┬───────────────────────────────┘ + │ +┌──────────────────────▼───────────────────────────────┐ +│ FILE SYSTEM (.planning/) │ +│ PROJECT.md | REQUIREMENTS.md | ROADMAP.md │ +│ STATE.md | config.json | phases/ | research/ │ +└──────────────────────────────────────────────────────┘ +``` + +--- + +## 설계 원칙 + +### 1. 에이전트별 새로운 컨텍스트 + +오케스트레이터가 생성하는 모든 에이전트는 새로운 컨텍스트 윈도우(최대 200K 토큰)를 받습니다. 이를 통해 컨텍스트 오염을 방지합니다 — AI가 컨텍스트 윈도우에 누적된 대화로 인해 품질이 저하되는 현상입니다. + +### 2. 가벼운 오케스트레이터 + +워크플로우 파일(`get-shit-done/workflows/*.md`)은 무거운 작업을 직접 수행하지 않습니다. 다음 작업만 담당합니다. +- `gsd-tools.cjs init `로 컨텍스트를 로드합니다 +- 집중된 프롬프트로 전문화된 에이전트를 생성합니다 +- 결과를 수집하여 다음 단계로 전달합니다 +- 단계 사이에 상태를 업데이트합니다 + +### 3. 파일 기반 상태 + +모든 상태는 `.planning/`에 사람이 읽을 수 있는 Markdown과 JSON으로 저장됩니다. 데이터베이스, 서버, 외부 의존성이 없습니다. 이를 통해 다음이 가능합니다. +- 컨텍스트 초기화(`/new`) 이후에도 상태가 유지됩니다 +- 사람과 에이전트 모두 상태를 확인할 수 있습니다 +- 팀 가시성을 위해 git에 커밋할 수 있습니다 + +### 4. 부재 = 활성화 + +워크플로우 기능 플래그는 **부재 = 활성화** 패턴을 따릅니다. `config.json`에 키가 없으면 기본값은 `true`입니다. 사용자는 기능을 명시적으로 비활성화하며 기본값을 활성화할 필요가 없습니다. + +### 5. 심층 방어 + +여러 레이어가 일반적인 실패 모드를 방지합니다. +- 계획은 실행 전에 검증됩니다 (plan-checker 에이전트) +- 실행은 작업당 원자적 커밋을 생성합니다 +- 실행 후 검증은 단계 목표에 대해 확인합니다 +- UAT는 최종 게이트로서 사람의 검증을 제공합니다 + +--- + +## 컴포넌트 아키텍처 + +### Commands (`commands/gsd/*.md`) + +사용자 대면 진입점입니다. 각 파일은 YAML 전문(name, description, allowed-tools)과 워크플로우를 부트스트랩하는 프롬프트 본문을 포함합니다. 명령어는 다음과 같이 설치됩니다. +- **OpenCode:** 커스텀 슬래시 명령어 (`/gsd-command-name`) +- **OpenCode:** 슬래시 명령어 (`/gsd-command-name`) +- **Codex:** Skills (`$gsd-command-name`) +- **Copilot:** 슬래시 명령어 (`/gsd-command-name`) +- **Antigravity:** Skills + +**전체 명령어 수:** 44개 + +### Workflows (`get-shit-done/workflows/*.md`) + +명령어가 참조하는 오케스트레이션 로직입니다. 다음을 포함하는 단계별 프로세스를 담습니다. +- `gsd-tools.cjs init`을 통한 컨텍스트 로드 +- 모델 해석을 포함한 에이전트 생성 지시 +- 게이트/체크포인트 정의 +- 상태 업데이트 패턴 +- 오류 처리 및 복구 + +**전체 워크플로우 수:** 46개 + +### Agents (`agents/*.md`) + +다음을 지정하는 전문화된 에이전트 정의 파일입니다. +- `name` — 에이전트 식별자 +- `description` — 역할과 목적 +- `tools` — 허용된 도구 접근 권한 (read, write, edit, bash, grep, glob, websearch 등) +- `color` — 시각적 구분을 위한 터미널 출력 색상 + +**전체 에이전트 수:** 16개 + +### References (`get-shit-done/references/*.md`) + +워크플로우와 에이전트가 `@-reference`로 참조하는 공유 지식 문서입니다. +- `checkpoints.md` — 체크포인트 유형 정의 및 상호작용 패턴 +- `model-profiles.md` — 에이전트별 모델 티어 할당 +- `verification-patterns.md` — 다양한 아티팩트 유형 검증 방법 +- `planning-config.md` — 전체 config 스키마 및 동작 +- `git-integration.md` — git 커밋, 브랜칭, 히스토리 패턴 +- `questioning.md` — 프로젝트 초기화를 위한 꿈 추출 철학 +- `tdd.md` — 테스트 주도 개발 통합 패턴 +- `ui-brand.md` — 시각적 출력 포매팅 패턴 + +### Templates (`get-shit-done/templates/`) + +모든 계획 아티팩트를 위한 Markdown 템플릿입니다. `gsd-tools.cjs template fill`과 `scaffold` 명령어가 사전 구조화된 파일을 생성하는 데 사용합니다. +- `project.md`, `requirements.md`, `roadmap.md`, `state.md` — 핵심 프로젝트 파일 +- `phase-prompt.md` — 단계 실행 프롬프트 템플릿 +- `summary.md` (+ `summary-minimal.md`, `summary-standard.md`, `summary-complex.md`) — 세분화 인식 요약 템플릿 +- `DEBUG.md` — 디버그 세션 추적 템플릿 +- `UI-SPEC.md`, `UAT.md`, `VALIDATION.md` — 전문화된 검증 템플릿 +- `discussion-log.md` — 논의 감사 추적 템플릿 +- `codebase/` — 브라운필드 매핑 템플릿 (stack, architecture, conventions, concerns, structure, testing, integrations) +- `research-project/` — 조사 출력 템플릿 (SUMMARY, STACK, FEATURES, ARCHITECTURE, PITFALLS) + +### Hooks (`hooks/`) + +호스트 AI 에이전트와 통합되는 런타임 훅입니다. + +| 훅 | 이벤트 | 목적 | +|------|-------|---------| +| `gsd-statusline.js` | `statusLine` | 모델, 작업, 디렉터리, 컨텍스트 사용 바 표시 | +| `gsd-context-monitor.js` | `PostToolUse` / `AfterTool` | 잔여 35%/25% 시점에 에이전트 대면 컨텍스트 경고 주입 | +| `gsd-check-update.js` | `SessionStart` | 새 GSD 버전을 백그라운드에서 확인 | +| `gsd-prompt-guard.js` | `PreToolUse` | `.planning/` 쓰기 작업에서 프롬프트 인젝션 패턴 스캔 (권고용) | +| `gsd-workflow-guard.js` | `PreToolUse` | GSD 워크플로우 컨텍스트 외부의 파일 편집 감지 (권고용, `hooks.workflow_guard`로 활성화) | + +### CLI Tools (`get-shit-done/bin/`) + +17개의 도메인 모듈을 포함하는 Node.js CLI 유틸리티(`gsd-tools.cjs`)입니다. + +| 모듈 | 역할 | +|--------|---------------| +| `core.cjs` | 오류 처리, 출력 포매팅, 공유 유틸리티 | +| `state.cjs` | STATE.md 파싱, 업데이트, 진행, 메트릭 | +| `phase.cjs` | 단계 디렉터리 작업, 소수 번호 매기기, 계획 인덱싱 | +| `roadmap.cjs` | ROADMAP.md 파싱, 단계 추출, 계획 진행 상황 | +| `config.cjs` | config.json 읽기/쓰기, 섹션 초기화 | +| `verify.cjs` | 계획 구조, 단계 완성도, 참조, 커밋 검증 | +| `template.cjs` | 변수 치환을 포함한 템플릿 선택 및 채우기 | +| `frontmatter.cjs` | YAML 전문 CRUD 작업 | +| `init.cjs` | 각 워크플로우 유형을 위한 복합 컨텍스트 로드 | +| `milestone.cjs` | 마일스톤 보관, 요구 사항 표시 | +| `commands.cjs` | 기타 명령어 (slug, timestamp, todos, scaffolding, stats) | +| `model-profiles.cjs` | 모델 프로필 해석 테이블 | +| `security.cjs` | 경로 탐색 방지, 프롬프트 인젝션 감지, 안전한 JSON 파싱, 셸 인수 검증 | +| `uat.cjs` | UAT 파일 파싱, 검증 부채 추적, audit-uat 지원 | + +--- + +## 에이전트 모델 + +### 오케스트레이터 → 에이전트 패턴 + +``` +Orchestrator (workflow .md) + │ + ├── Load context: gsd-tools.cjs init + │ Returns JSON with: project info, config, state, phase details + │ + ├── Resolve model: gsd-tools.cjs resolve-model + │ Returns: opus | sonnet | haiku | inherit + │ + ├── Spawn Agent (task/SubAgent call) + │ ├── Agent prompt (agents/*.md) + │ ├── Context payload (init JSON) + │ ├── Model assignment + │ └── Tool permissions + │ + ├── Collect result + │ + └── Update state: gsd-tools.cjs state update/patch/advance-plan +``` + +### 에이전트 생성 카테고리 + +| 카테고리 | 에이전트 | 병렬성 | +|----------|--------|-------------| +| **Researchers** | gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher, gsd-advisor-researcher | 4개 병렬 (stack, features, architecture, pitfalls); advisor는 discuss-phase 중 생성됨 | +| **Synthesizers** | gsd-research-synthesizer | 순차적 (조사자 완료 후) | +| **Planners** | gsd-planner, gsd-roadmapper | 순차적 | +| **Checkers** | gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor | 순차적 (검증 루프, 최대 3회 반복) | +| **Executors** | gsd-executor | 웨이브 내 병렬, 웨이브 간 순차적 | +| **Verifiers** | gsd-verifier | 순차적 (모든 executor 완료 후) | +| **Mappers** | gsd-codebase-mapper | 4개 병렬 (tech, arch, quality, concerns) | +| **Debuggers** | gsd-debugger | 순차적 (대화형) | +| **Auditors** | gsd-ui-auditor | 순차적 | + +### 웨이브 실행 모델 + +`execute-phase` 중 계획은 의존성 웨이브로 그룹화됩니다. + +``` +Wave Analysis: + Plan 01 (no deps) ─┐ + Plan 02 (no deps) ─┤── Wave 1 (parallel) + Plan 03 (depends: 01) ─┤── Wave 2 (waits for Wave 1) + Plan 04 (depends: 02) ─┘ + Plan 05 (depends: 03,04) ── Wave 3 (waits for Wave 2) +``` + +각 executor는 다음을 받습니다. +- 새로운 200K 컨텍스트 윈도우 +- 실행할 특정 PLAN.md +- 프로젝트 컨텍스트 (PROJECT.md, STATE.md) +- 단계 컨텍스트 (CONTEXT.md, 사용 가능한 경우 RESEARCH.md) + +#### 병렬 커밋 안전성 + +같은 웨이브 내에서 여러 executor가 실행될 때 충돌을 방지하는 두 가지 메커니즘이 있습니다. + +1. **`--no-verify` 커밋** — 병렬 에이전트는 사전 커밋 훅을 건너뜁니다 (빌드 잠금 경쟁을 유발할 수 있음, 예: Rust 프로젝트의 cargo lock 충돌). 오케스트레이터는 각 웨이브 완료 후 `git hook run pre-commit`을 한 번 실행합니다. + +2. **STATE.md 파일 잠금** — 모든 `writeStateMd()` 호출은 lockfile 기반 상호 배제를 사용합니다 (`STATE.md.lock`, `O_EXCL` 원자적 생성). 이는 두 에이전트가 STATE.md를 읽고 서로 다른 필드를 수정하면 마지막 작성자가 다른 에이전트의 변경사항을 덮어쓰는 읽기-수정-쓰기 경쟁 조건을 방지합니다. 오래된 잠금 감지(10초 타임아웃)와 지터를 포함한 스핀 대기가 포함됩니다. + +--- + +## 데이터 흐름 + +### 새 프로젝트 흐름 + +``` +User input (idea description) + │ + ▼ +Questions (questioning.md philosophy) + │ + ▼ +4x Project Researchers (parallel) + ├── Stack → STACK.md + ├── Features → FEATURES.md + ├── Architecture → ARCHITECTURE.md + └── Pitfalls → PITFALLS.md + │ + ▼ +Research Synthesizer → SUMMARY.md + │ + ▼ +Requirements extraction → REQUIREMENTS.md + │ + ▼ +Roadmapper → ROADMAP.md + │ + ▼ +User approval → STATE.md initialized +``` + +### 단계 실행 흐름 + +``` +discuss-phase → CONTEXT.md (user preferences) + │ + ▼ +ui-phase → UI-SPEC.md (design contract, optional) + │ + ▼ +plan-phase + ├── Phase Researcher → RESEARCH.md + ├── Planner → PLAN.md files + └── Plan Checker → Verify loop (max 3x) + │ + ▼ +execute-phase + ├── Wave analysis (dependency grouping) + ├── Executor per plan → code + atomic commits + ├── SUMMARY.md per plan + └── Verifier → VERIFICATION.md + │ + ▼ +verify-work → UAT.md (user acceptance testing) + │ + ▼ +ui-review → UI-REVIEW.md (visual audit, optional) +``` + +### 컨텍스트 전파 + +각 워크플로우 단계는 이후 단계에 공급되는 아티팩트를 생성합니다. + +``` +PROJECT.md ────────────────────────────────────────────► All agents +REQUIREMENTS.md ───────────────────────────────────────► Planner, Verifier, Auditor +ROADMAP.md ────────────────────────────────────────────► Orchestrators +STATE.md ──────────────────────────────────────────────► All agents (decisions, blockers) +CONTEXT.md (per phase) ────────────────────────────────► Researcher, Planner, Executor +RESEARCH.md (per phase) ───────────────────────────────► Planner, Plan Checker +PLAN.md (per plan) ────────────────────────────────────► Executor, Plan Checker +SUMMARY.md (per plan) ─────────────────────────────────► Verifier, State tracking +UI-SPEC.md (per phase) ────────────────────────────────► Executor, UI Auditor +``` + +--- + +## 파일 시스템 구조 + +### 설치 파일 + +``` +$HOME/.config/opencode/ # OpenCode (전역 설치) +├── commands/gsd/*.md # 37개 슬래시 명령어 +├── get-shit-done/ +│ ├── bin/gsd-tools.cjs # CLI 유틸리티 +│ ├── bin/lib/*.cjs # 15개 도메인 모듈 +│ ├── workflows/*.md # 42개 워크플로우 정의 +│ ├── references/*.md # 13개 공유 참조 문서 +│ └── templates/ # 계획 아티팩트 템플릿 +├── agents/*.md # 15개 에이전트 정의 +├── hooks/ +│ ├── gsd-statusline.js # 상태표시줄 훅 +│ ├── gsd-context-monitor.js # 컨텍스트 경고 훅 +│ └── gsd-check-update.js # 업데이트 확인 훅 +├── settings.json # 훅 등록 +└── VERSION # 설치된 버전 번호 +``` + +다른 런타임의 동등한 경로입니다. +- **OpenCode:** `~/.config/opencode/` 또는 `~/.opencode/` +- **Gemini CLI:** `~/.gemini/` +- **Codex:** `~/.codex/` (명령어 대신 skills 사용) +- **Copilot:** `~/.github/` +- **Antigravity:** `~/.gemini/antigravity/` (전역) 또는 `./.agent/` (로컬) + +### 프로젝트 파일 (`.planning/`) + +``` +.planning/ +├── PROJECT.md # 프로젝트 비전, 제약, 결정, 진화 규칙 +├── REQUIREMENTS.md # 범위 지정된 요구 사항 (v1/v2/범위 외) +├── ROADMAP.md # 상태 추적을 포함한 단계 분류 +├── STATE.md # 살아있는 메모리: 위치, 결정, 차단, 메트릭 +├── config.json # 워크플로우 설정 +├── MILESTONES.md # 완료된 마일스톤 보관 +├── research/ # /gsd-new-project의 도메인 조사 +│ ├── SUMMARY.md +│ ├── STACK.md +│ ├── FEATURES.md +│ ├── ARCHITECTURE.md +│ └── PITFALLS.md +├── codebase/ # 브라운필드 매핑 (/gsd-map-codebase에서) +│ ├── STACK.md +│ ├── ARCHITECTURE.md +│ ├── CONVENTIONS.md +│ ├── CONCERNS.md +│ ├── STRUCTURE.md +│ ├── TESTING.md +│ └── INTEGRATIONS.md +├── phases/ +│ └── XX-phase-name/ +│ ├── XX-CONTEXT.md # 사용자 선호도 (discuss-phase에서) +│ ├── XX-RESEARCH.md # 생태계 조사 (plan-phase에서) +│ ├── XX-YY-PLAN.md # 실행 계획 +│ ├── XX-YY-SUMMARY.md # 실행 결과 +│ ├── XX-VERIFICATION.md # 실행 후 검증 +│ ├── XX-VALIDATION.md # Nyquist 테스트 커버리지 매핑 +│ ├── XX-UI-SPEC.md # UI 디자인 계약서 (ui-phase에서) +│ ├── XX-UI-REVIEW.md # 시각적 감사 점수 (ui-review에서) +│ └── XX-UAT.md # 사용자 수용 테스트 결과 +├── quick/ # 빠른 작업 추적 +│ └── YYMMDD-xxx-slug/ +│ ├── PLAN.md +│ └── SUMMARY.md +├── todos/ +│ ├── pending/ # 캡처된 아이디어 +│ └── done/ # 완료된 할 일 +├── threads/ # 영구 컨텍스트 스레드 (/gsd-thread에서) +├── seeds/ # 미래 지향적 아이디어 (/gsd-plant-seed에서) +├── debug/ # 활성 디버그 세션 +│ ├── *.md # 활성 세션 +│ ├── resolved/ # 보관된 세션 +│ └── knowledge-base.md # 영구 디버그 학습 내용 +├── ui-reviews/ # /gsd-ui-review의 스크린샷 (gitignored) +└── continue-here.md # 컨텍스트 핸드오프 (pause-work에서) +``` + +--- + +## 인스톨러 아키텍처 + +인스톨러(`bin/install.js`, ~3,000줄)는 다음을 처리합니다. + +1. **런타임 감지** — 대화형 프롬프트 또는 CLI 플래그 (`--OpenCode`, `--opencode`, `--gemini`, `--codex`, `--copilot`, `--antigravity`, `--all`) +2. **위치 선택** — 전역(`--global`) 또는 로컬(`--local`) +3. **파일 배포** — commands, workflows, references, templates, agents, hooks 복사 +4. **런타임 적응** — 런타임별 파일 내용 변환. + - OpenCode: 그대로 사용 + - OpenCode: 에이전트 전문을 `name:`, `model: inherit`, `mode: subagent`로 변환 + - Codex: commands에서 TOML config + skills 생성 + - Copilot: 도구 이름 매핑 (read→read, bash→execute 등) + - Gemini: 훅 이벤트 이름 조정 (`PostToolUse` 대신 `AfterTool`) + - Antigravity: Google 모델 등가물을 사용한 skills-first 방식 +5. **경로 정규화** — `$HOME/.config/opencode/` 경로를 런타임별 경로로 교체 +6. **설정 통합** — 런타임의 `settings.json`에 훅 등록 +7. **패치 백업** — v1.17부터 로컬 수정 파일을 `gsd-local-patches/`에 백업하여 `/gsd-reapply-patches`에 사용 +8. **매니페스트 추적** — 깔끔한 제거를 위해 `gsd-file-manifest.json` 작성 +9. **제거 모드** — `--uninstall`로 모든 GSD 파일, 훅, 설정 제거 + +### 플랫폼 처리 + +- **Windows:** 자식 프로세스에 `windowsHide` 적용, 보호 디렉터리의 EPERM/EACCES 방지, 경로 구분자 정규화 +- **WSL:** WSL에서 실행 중인 Windows Node.js를 감지하고 경로 불일치에 대해 경고 +- **Docker/CI:** 커스텀 config 디렉터리 위치를 위한 `CLAUDE_CONFIG_DIR` 환경 변수 지원 + +--- + +## 훅 시스템 + +### 아키텍처 + +``` +Runtime Engine (OpenCode / Gemini CLI) + │ + ├── statusLine event ──► gsd-statusline.js + │ Reads: stdin (session JSON) + │ Writes: stdout (formatted status), /tmp/OpenCode-ctx-{session}.json (bridge) + │ + ├── PostToolUse/AfterTool event ──► gsd-context-monitor.js + │ Reads: stdin (tool event JSON), /tmp/OpenCode-ctx-{session}.json (bridge) + │ Writes: stdout (hookSpecificOutput with additionalContext warning) + │ + └── SessionStart event ──► gsd-check-update.js + Reads: VERSION file + Writes: $HOME/.config/opencode/cache/gsd-update-check.json (spawns background process) +``` + +### 컨텍스트 모니터 임계값 + +| 잔여 컨텍스트 | 수준 | 에이전트 동작 | +|-------------------|-------|----------------| +| > 35% | 정상 | 경고 주입 없음 | +| ≤ 35% | WARNING | "복잡한 새 작업 시작을 피하세요" | +| ≤ 25% | CRITICAL | "컨텍스트가 거의 소진됨, 사용자에게 알리세요" | + +디바운스: 반복 경고 사이에 5회 도구 사용. 심각도 에스컬레이션(WARNING→CRITICAL)은 디바운스를 우회합니다. + +### 안전 속성 + +- 모든 훅은 try/catch로 감싸여 있으며 오류 시 자동 종료합니다 +- stdin 타임아웃 가드(3초)로 파이프 문제 시 중단 방지 +- 오래된 메트릭(60초 이상)은 무시됩니다 +- 누락된 브리지 파일은 정상적으로 처리됩니다 (서브에이전트, 새 세션) +- 컨텍스트 모니터는 권고용입니다 — 사용자 선호도를 재정의하는 명령을 내리지 않습니다 + +### 보안 훅 (v1.27) + +**Prompt Guard** (`gsd-prompt-guard.js`). +- `.planning/` 파일에 write/edit 시 트리거됩니다 +- 프롬프트 인젝션 패턴을 콘텐츠에서 스캔합니다 (역할 재정의, 지시 우회, system 태그 인젝션) +- 권고용 — 감지를 기록하며 차단하지 않습니다 +- 패턴은 훅 독립성을 위해 인라인으로 포함됩니다 (`security.cjs`의 일부) + +**Workflow Guard** (`gsd-workflow-guard.js`). +- `.planning/` 외부 파일에 write/edit 시 트리거됩니다 +- GSD 워크플로우 컨텍스트 외부의 편집을 감지합니다 (활성 `/gsd-` 명령어 또는 task 서브에이전트 없음) +- 상태 추적 변경을 위해 `/gsd-quick` 또는 `/gsd-fast` 사용을 권고합니다 +- `hooks.workflow_guard: true`로 활성화 (기본값: false) + +--- + +## 런타임 추상화 + +GSD는 통합된 명령어/워크플로우 아키텍처를 통해 6개의 AI 코딩 런타임을 지원합니다. + +| 런타임 | 명령어 형식 | 에이전트 시스템 | 설정 위치 | +|---------|---------------|--------------|-----------------| +| OpenCode | `/gsd-command` | task 생성 | `$HOME/.config/opencode/` | +| OpenCode | `/gsd-command` | Subagent 모드 | `~/.config/opencode/` | +| Gemini CLI | `/gsd-command` | task 생성 | `~/.gemini/` | +| Codex | `$gsd-command` | Skills | `~/.codex/` | +| Copilot | `/gsd-command` | 에이전트 위임 | `~/.github/` | +| Antigravity | Skills | Skills | `~/.gemini/antigravity/` | + +### 추상화 포인트 + +1. **도구 이름 매핑** — 각 런타임은 고유한 도구 이름을 가집니다 (예: OpenCode의 `bash` → Copilot의 `execute`) +2. **훅 이벤트 이름** — OpenCode는 `PostToolUse`를 사용하고 Gemini는 `AfterTool`을 사용합니다 +3. **에이전트 전문** — 각 런타임은 고유한 에이전트 정의 형식을 가집니다 +4. **경로 규칙** — 각 런타임은 서로 다른 디렉터리에 설정을 저장합니다 +5. **모델 참조** — `inherit` 프로필을 통해 GSD가 런타임의 모델 선택에 위임합니다 + +인스톨러는 설치 시 모든 변환을 처리합니다. 워크플로우와 에이전트는 OpenCode의 네이티브 형식으로 작성되어 배포 중에 변환됩니다. diff --git a/gsd-opencode/docs/ko-KR/CLI-TOOLS.md b/gsd-opencode/docs/ko-KR/CLI-TOOLS.md new file mode 100644 index 0000000..9f9ff86 --- /dev/null +++ b/gsd-opencode/docs/ko-KR/CLI-TOOLS.md @@ -0,0 +1,367 @@ +# GSD CLI 도구 레퍼런스 + +> `gsd-tools.cjs`에 대한 프로그래밍 방식 API 레퍼런스입니다. 워크플로우와 에이전트가 내부적으로 사용합니다. 사용자 대면 명령어는 [Command Reference](COMMANDS.md)를 참조하세요. + +--- + +## 개요 + +`gsd-tools.cjs`는 GSD의 약 50개 명령어, 워크플로우, 에이전트 파일에서 반복되는 인라인 bash 패턴을 대체하는 Node.js CLI 유틸리티입니다. config 파싱, 모델 해석, 단계 조회, git 커밋, 요약 검증, 상태 관리, 템플릿 작업을 중앙화합니다. + +**위치:** `get-shit-done/bin/gsd-tools.cjs` +**모듈:** `get-shit-done/bin/lib/`의 15개 도메인 모듈 + +**사용법:** +```bash +node gsd-tools.cjs [args] [--raw] [--cwd ] +``` + +**전역 플래그.** +| 플래그 | 설명 | +|------|-------------| +| `--raw` | 기계 가독형 출력 (JSON 또는 일반 텍스트, 포매팅 없음) | +| `--cwd ` | 작업 디렉터리 재정의 (샌드박스 서브에이전트용) | + +--- + +## State 명령어 + +`.planning/STATE.md`를 관리합니다 — 프로젝트의 살아있는 메모리입니다. + +```bash +# 전체 프로젝트 config + state를 JSON으로 로드 +node gsd-tools.cjs state load + +# STATE.md 전문을 JSON으로 출력 +node gsd-tools.cjs state json + +# 단일 필드 업데이트 +node gsd-tools.cjs state update + +# STATE.md 내용 또는 특정 섹션 가져오기 +node gsd-tools.cjs state get [section] + +# 여러 필드를 일괄 업데이트 +node gsd-tools.cjs state patch --field1 val1 --field2 val2 + +# 계획 카운터 증가 +node gsd-tools.cjs state advance-plan + +# 실행 메트릭 기록 +node gsd-tools.cjs state record-metric --phase N --plan M --duration Xmin [--tasks N] [--files N] + +# 진행률 바 재계산 +node gsd-tools.cjs state update-progress + +# 결정 추가 +node gsd-tools.cjs state add-decision --summary "..." [--phase N] [--rationale "..."] +# 또는 파일에서: +node gsd-tools.cjs state add-decision --summary-file path [--rationale-file path] + +# 차단 항목 추가/해결 +node gsd-tools.cjs state add-blocker --text "..." +node gsd-tools.cjs state resolve-blocker --text "..." + +# 세션 연속성 기록 +node gsd-tools.cjs state record-session --stopped-at "..." [--resume-file path] +``` + +### State Snapshot + +전체 STATE.md의 구조화된 파싱 결과입니다. + +```bash +node gsd-tools.cjs state-snapshot +``` + +현재 위치, 단계, 계획, 상태, 결정, 차단, 메트릭, 최근 활동을 포함한 JSON을 반환합니다. + +--- + +## Phase 명령어 + +단계를 관리합니다 — 디렉터리, 번호 매기기, 로드맵 동기화. + +```bash +# 번호로 단계 디렉터리 찾기 +node gsd-tools.cjs find-phase + +# 삽입을 위한 다음 소수 단계 번호 계산 +node gsd-tools.cjs phase next-decimal + +# 로드맵에 새 단계 추가 + 디렉터리 생성 +node gsd-tools.cjs phase add + +# 기존 단계 이후에 소수 단계 삽입 +node gsd-tools.cjs phase insert + +# 단계 제거, 이후 단계 재번호 매기기 +node gsd-tools.cjs phase remove [--force] + +# 단계 완료 표시, state + roadmap 업데이트 +node gsd-tools.cjs phase complete + +# 웨이브와 상태를 포함한 계획 인덱싱 +node gsd-tools.cjs phase-plan-index + +# 필터링을 포함한 단계 목록 +node gsd-tools.cjs phases list [--type planned|executed|all] [--phase N] [--include-archived] +``` + +--- + +## Roadmap 명령어 + +`ROADMAP.md`를 파싱하고 업데이트합니다. + +```bash +# ROADMAP.md에서 단계 섹션 추출 +node gsd-tools.cjs roadmap get-phase + +# 디스크 상태를 포함한 전체 로드맵 파싱 +node gsd-tools.cjs roadmap analyze + +# 디스크에서 진행률 표 행 업데이트 +node gsd-tools.cjs roadmap update-plan-progress +``` + +--- + +## Config 명령어 + +`.planning/config.json`을 읽고 씁니다. + +```bash +# config.json을 기본값으로 초기화 +node gsd-tools.cjs config-ensure-section + +# config 값 설정 (점 표기법) +node gsd-tools.cjs config-set + +# config 값 가져오기 +node gsd-tools.cjs config-get + +# 모델 프로필 설정 +node gsd-tools.cjs config-set-model-profile +``` + +--- + +## 모델 해석 + +```bash +# 현재 프로필 기반으로 에이전트 모델 가져오기 +node gsd-tools.cjs resolve-model +# 반환값: opus | sonnet | haiku | inherit +``` + +에이전트 이름: `gsd-planner`, `gsd-executor`, `gsd-phase-researcher`, `gsd-project-researcher`, `gsd-research-synthesizer`, `gsd-verifier`, `gsd-plan-checker`, `gsd-integration-checker`, `gsd-roadmapper`, `gsd-debugger`, `gsd-codebase-mapper`, `gsd-nyquist-auditor` + +--- + +## Verification 명령어 + +계획, 단계, 참조, 커밋을 검증합니다. + +```bash +# SUMMARY.md 파일 검증 +node gsd-tools.cjs verify-summary [--check-count N] + +# PLAN.md 구조 + 작업 확인 +node gsd-tools.cjs verify plan-structure + +# 모든 계획에 요약이 있는지 확인 +node gsd-tools.cjs verify phase-completeness + +# @-참조 + 경로 해석 확인 +node gsd-tools.cjs verify references + +# 커밋 해시 일괄 검증 +node gsd-tools.cjs verify commits [hash2] ... + +# must_haves.artifacts 확인 +node gsd-tools.cjs verify artifacts + +# must_haves.key_links 확인 +node gsd-tools.cjs verify key-links +``` + +--- + +## Validation 명령어 + +프로젝트 무결성을 확인합니다. + +```bash +# 단계 번호 매기기, 디스크/로드맵 동기화 확인 +node gsd-tools.cjs validate consistency + +# .planning/ 무결성 확인, 선택적으로 복구 +node gsd-tools.cjs validate health [--repair] +``` + +--- + +## Template 명령어 + +템플릿 선택 및 채우기입니다. + +```bash +# 세분화에 따른 요약 템플릿 선택 +node gsd-tools.cjs template select + +# 변수로 템플릿 채우기 +node gsd-tools.cjs template fill --phase N [--plan M] [--name "..."] [--type execute|tdd] [--wave N] [--fields '{json}'] +``` + +`fill`의 템플릿 유형: `summary`, `plan`, `verification` + +--- + +## Frontmatter 명령어 + +모든 Markdown 파일에 대한 YAML 전문 CRUD 작업입니다. + +```bash +# 전문을 JSON으로 추출 +node gsd-tools.cjs frontmatter get [--field key] + +# 단일 필드 업데이트 +node gsd-tools.cjs frontmatter set --field key --value jsonVal + +# JSON을 전문에 병합 +node gsd-tools.cjs frontmatter merge --data '{json}' + +# 필수 필드 검증 +node gsd-tools.cjs frontmatter validate --schema plan|summary|verification +``` + +--- + +## Scaffold 명령어 + +사전 구조화된 파일과 디렉터리를 생성합니다. + +```bash +# CONTEXT.md 템플릿 생성 +node gsd-tools.cjs scaffold context --phase N + +# UAT.md 템플릿 생성 +node gsd-tools.cjs scaffold uat --phase N + +# VERIFICATION.md 템플릿 생성 +node gsd-tools.cjs scaffold verification --phase N + +# 단계 디렉터리 생성 +node gsd-tools.cjs scaffold phase-dir --phase N --name "phase name" +``` + +--- + +## Init 명령어 (복합 컨텍스트 로드) + +특정 워크플로우에 필요한 모든 컨텍스트를 단일 호출로 로드합니다. 프로젝트 정보, config, state, 워크플로우별 데이터를 포함한 JSON을 반환합니다. + +```bash +node gsd-tools.cjs init execute-phase +node gsd-tools.cjs init plan-phase +node gsd-tools.cjs init new-project +node gsd-tools.cjs init new-milestone +node gsd-tools.cjs init quick +node gsd-tools.cjs init resume +node gsd-tools.cjs init verify-work +node gsd-tools.cjs init phase-op +node gsd-tools.cjs init todos [area] +node gsd-tools.cjs init milestone-op +node gsd-tools.cjs init map-codebase +node gsd-tools.cjs init progress +``` + +**대용량 페이로드 처리:** 출력이 약 50KB를 초과하면 CLI가 임시 파일에 쓰고 `@file:/tmp/gsd-init-XXXXX.json`을 반환합니다. 워크플로우는 `@file:` 접두사를 확인하고 디스크에서 읽습니다. + +```bash +INIT=$(node gsd-tools.cjs init execute-phase "1") +if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +``` + +--- + +## Milestone 명령어 + +```bash +# 마일스톤 보관 +node gsd-tools.cjs milestone complete [--name ] [--archive-phases] + +# 요구 사항을 완료로 표시 +node gsd-tools.cjs requirements mark-complete +# 허용 형식: REQ-01,REQ-02 또는 REQ-01 REQ-02 또는 [REQ-01, REQ-02] +``` + +--- + +## 유틸리티 명령어 + +```bash +# 텍스트를 URL 안전 슬러그로 변환 +node gsd-tools.cjs generate-slug "Some Text Here" +# → some-text-here + +# 타임스탬프 가져오기 +node gsd-tools.cjs current-timestamp [full|date|filename] + +# 대기 중인 할 일 개수 및 목록 +node gsd-tools.cjs list-todos [area] + +# 파일/디렉터리 존재 확인 +node gsd-tools.cjs verify-path-exists + +# 모든 SUMMARY.md 데이터 집계 +node gsd-tools.cjs history-digest + +# SUMMARY.md에서 구조화된 데이터 추출 +node gsd-tools.cjs summary-extract [--fields field1,field2] + +# 프로젝트 통계 +node gsd-tools.cjs stats [json|table] + +# 진행률 렌더링 +node gsd-tools.cjs progress [json|table|bar] + +# 할 일 완료 처리 +node gsd-tools.cjs todo complete + +# UAT 감사 — 모든 단계에서 미해결 항목 스캔 +node gsd-tools.cjs audit-uat + +# config 확인을 포함한 git 커밋 +node gsd-tools.cjs commit [--files f1 f2] [--amend] [--no-verify] +``` + +> **`--no-verify`**: 사전 커밋 훅을 건너뜁니다. 빌드 잠금 경쟁을 피하기 위해 웨이브 기반 실행 중 병렬 executor 에이전트가 사용합니다 (예: Rust 프로젝트의 cargo lock 충돌). 오케스트레이터는 각 웨이브 완료 후 훅을 한 번 실행합니다. 순차 실행 중에는 `--no-verify`를 사용하지 마세요 — 훅이 정상적으로 실행되어야 합니다. + +```bash +# 웹 검색 (Brave API 키 필요) +node gsd-tools.cjs websearch [--limit N] [--freshness day|week|month] +``` + +--- + +## 모듈 아키텍처 + +| 모듈 | 파일 | 내보내기 | +|--------|------|---------| +| Core | `lib/core.cjs` | `error()`, `output()`, `parseArgs()`, 공유 유틸리티 | +| State | `lib/state.cjs` | 모든 `state` 하위 명령어, `state-snapshot` | +| Phase | `lib/phase.cjs` | Phase CRUD, `find-phase`, `phase-plan-index`, `phases list` | +| Roadmap | `lib/roadmap.cjs` | 로드맵 파싱, 단계 추출, 진행률 업데이트 | +| Config | `lib/config.cjs` | Config 읽기/쓰기, 섹션 초기화 | +| Verify | `lib/verify.cjs` | 모든 verification 및 validation 명령어 | +| Template | `lib/template.cjs` | 템플릿 선택 및 변수 채우기 | +| Frontmatter | `lib/frontmatter.cjs` | YAML 전문 CRUD | +| Init | `lib/init.cjs` | 모든 워크플로우를 위한 복합 컨텍스트 로드 | +| Milestone | `lib/milestone.cjs` | 마일스톤 보관, 요구 사항 표시 | +| Commands | `lib/commands.cjs` | 기타: slug, timestamp, todos, scaffold, stats, websearch | +| Model Profiles | `lib/model-profiles.cjs` | 프로필 해석 테이블 | +| UAT | `lib/uat.cjs` | 단계 간 UAT/verification 감사 | +| Profile Output | `lib/profile-output.cjs` | 개발자 프로필 포매팅 | +| Profile Pipeline | `lib/profile-pipeline.cjs` | 세션 분석 파이프라인 | diff --git a/gsd-opencode/docs/ko-KR/COMMANDS.md b/gsd-opencode/docs/ko-KR/COMMANDS.md new file mode 100644 index 0000000..2172144 --- /dev/null +++ b/gsd-opencode/docs/ko-KR/COMMANDS.md @@ -0,0 +1,933 @@ +# GSD 명령어 레퍼런스 + +> 전체 명령어 문법, 플래그, 옵션, 사용 예시를 다룹니다. 기능 상세 설명은 [Feature Reference](FEATURES.md)를 참고하세요. 워크플로우 안내는 [User Guide](USER-GUIDE.md)를 참고하세요. + +--- + +## 명령어 문법 + +- **OpenCode / Gemini / Copilot:** `/gsd-command-name [args]` +- **OpenCode:** `/gsd-command-name [args]` +- **Codex:** `$gsd-command-name [args]` + +--- + +## 핵심 워크플로우 명령어 + +### `/gsd-new-project` + +심층 컨텍스트 수집을 통해 새 프로젝트를 초기화합니다. + +| 플래그 | 설명 | +|--------|------| +| `--auto @file.md` | 문서에서 자동으로 정보를 추출하고 대화형 질문을 건너뜁니다 | + +**사전 조건:** `.planning/PROJECT.md`가 존재하지 않아야 합니다. +**생성 파일:** `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, `config.json`, `research/`, `AGENTS.md` + +```bash +/gsd-new-project # 대화형 모드 +/gsd-new-project --auto @prd.md # PRD에서 자동 추출 +``` + +--- + +### `/gsd-new-workspace` + +격리된 워크스페이스를 생성합니다. 저장소 복사본과 독립적인 `.planning/` 디렉터리가 포함됩니다. + +| 플래그 | 설명 | +|--------|------| +| `--name ` | 워크스페이스 이름 (필수) | +| `--repos repo1,repo2` | 쉼표로 구분된 저장소 경로 또는 이름 | +| `--path /target` | 대상 디렉터리 (기본값: `~/gsd-workspaces/`) | +| `--strategy worktree\|clone` | 복사 전략 (기본값: `worktree`) | +| `--branch ` | 체크아웃할 브랜치 (기본값: `workspace/`) | +| `--auto` | 대화형 질문을 건너뜁니다 | + +**사용 사례.** +- 멀티 저장소: 격리된 GSD 상태로 일부 저장소만 작업합니다. +- 기능 격리: `--repos .`는 현재 저장소의 worktree를 생성합니다. + +**생성 파일:** `WORKSPACE.md`, `.planning/`, 저장소 복사본 (worktree 또는 clone) + +```bash +/gsd-new-workspace --name feature-b --repos hr-ui,ZeymoAPI +/gsd-new-workspace --name feature-b --repos . --strategy worktree # 동일 저장소 격리 +/gsd-new-workspace --name spike --repos api,web --strategy clone # 전체 클론 +``` + +--- + +### `/gsd-list-workspaces` + +활성 GSD 워크스페이스와 상태를 목록으로 표시합니다. + +**스캔 위치:** `~/gsd-workspaces/`에서 `WORKSPACE.md` 매니페스트를 탐색합니다. +**표시 항목:** 이름, 저장소 수, 전략, GSD 프로젝트 상태 + +```bash +/gsd-list-workspaces +``` + +--- + +### `/gsd-remove-workspace` + +워크스페이스를 제거하고 git worktree를 정리합니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `` | 예 | 제거할 워크스페이스 이름 | + +**안전 장치:** 저장소에 커밋되지 않은 변경사항이 있으면 제거를 거부합니다. 이름 확인이 필요합니다. + +```bash +/gsd-remove-workspace feature-b +``` + +--- + +### `/gsd-discuss-phase` + +계획 수립 전에 구현 결정사항을 캡처합니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `N` | 아니오 | 페이즈 번호 (기본값: 현재 페이즈) | + +| 플래그 | 설명 | +|--------|------| +| `--auto` | 모든 질문에 추천 기본값을 자동으로 선택합니다 | +| `--batch` | 질문을 하나씩 처리하는 대신 일괄 입력 방식으로 그룹화합니다 | +| `--analyze` | 토론 중 트레이드오프 분석을 추가합니다 | + +**사전 조건:** `.planning/ROADMAP.md`가 존재해야 합니다. +**생성 파일:** `{phase}-CONTEXT.md`, `{phase}-DISCUSSION-LOG.md` (감사 추적) + +```bash +/gsd-discuss-phase 1 # 페이즈 1 대화형 토론 +/gsd-discuss-phase 3 --auto # 페이즈 3 기본값 자동 선택 +/gsd-discuss-phase --batch # 현재 페이즈 일괄 모드 +/gsd-discuss-phase 2 --analyze # 트레이드오프 분석 포함 토론 +``` + +--- + +### `/gsd-ui-phase` + +프론트엔드 페이즈를 위한 UI 설계 계약을 생성합니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `N` | 아니오 | 페이즈 번호 (기본값: 현재 페이즈) | + +**사전 조건:** `.planning/ROADMAP.md`가 존재해야 하며 해당 페이즈에 프론트엔드/UI 작업이 포함되어야 합니다. +**생성 파일:** `{phase}-UI-SPEC.md` + +```bash +/gsd-ui-phase 2 # 페이즈 2 설계 계약 생성 +``` + +--- + +### `/gsd-plan-phase` + +페이즈를 조사하고 계획하며 검증합니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `N` | 아니오 | 페이즈 번호 (기본값: 다음 미계획 페이즈) | + +| 플래그 | 설명 | +|--------|------| +| `--auto` | 대화형 확인을 건너뜁니다 | +| `--research` | RESEARCH.md가 있어도 재조사를 강제합니다 | +| `--skip-research` | 도메인 조사 단계를 건너뜁니다 | +| `--gaps` | 갭 보완 모드 (VERIFICATION.md를 읽고 조사를 건너뜁니다) | +| `--skip-verify` | 계획 검증 루프를 건너뜁니다 | +| `--prd ` | discuss-phase 대신 PRD 파일을 컨텍스트로 사용합니다 | +| `--reviews` | REVIEWS.md의 교차 AI 리뷰 피드백으로 재계획합니다 | + +**사전 조건:** `.planning/ROADMAP.md`가 존재해야 합니다. +**생성 파일:** `{phase}-RESEARCH.md`, `{phase}-{N}-PLAN.md`, `{phase}-VALIDATION.md` + +```bash +/gsd-plan-phase 1 # 페이즈 1 조사 + 계획 + 검증 +/gsd-plan-phase 3 --skip-research # 조사 없이 계획 (익숙한 도메인) +/gsd-plan-phase --auto # 비대화형 계획 수립 +``` + +--- + +### `/gsd-execute-phase` + +페이즈의 모든 계획을 웨이브 기반 병렬화로 실행하거나 특정 웨이브만 실행합니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `N` | **예** | 실행할 페이즈 번호 | +| `--wave N` | 아니오 | 페이즈 내 Wave `N`만 실행합니다 | + +**사전 조건:** 페이즈에 PLAN.md 파일이 있어야 합니다. +**생성 파일:** 계획별 `{phase}-{N}-SUMMARY.md`, git 커밋, 페이즈가 완전히 완료되면 `{phase}-VERIFICATION.md` + +```bash +/gsd-execute-phase 1 # 페이즈 1 실행 +/gsd-execute-phase 1 --wave 2 # Wave 2만 실행 +``` + +--- + +### `/gsd-verify-work` + +자동 진단을 포함한 사용자 인수 테스트(UAT)를 수행합니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `N` | 아니오 | 페이즈 번호 (기본값: 마지막 실행된 페이즈) | + +**사전 조건:** 페이즈가 실행되어 있어야 합니다. +**생성 파일:** `{phase}-UAT.md`, 문제 발견 시 수정 계획 + +```bash +/gsd-verify-work 1 # 페이즈 1 UAT +``` + +--- + +### `/gsd-next` + +다음 논리적 워크플로우 단계로 자동으로 이동합니다. 프로젝트 상태를 읽고 적절한 명령어를 실행합니다. + +**사전 조건:** `.planning/` 디렉터리가 존재해야 합니다. +**동작 방식.** +- 프로젝트 없음 → `/gsd-new-project` 제안 +- 페이즈 토론 필요 → `/gsd-discuss-phase` 실행 +- 페이즈 계획 필요 → `/gsd-plan-phase` 실행 +- 페이즈 실행 필요 → `/gsd-execute-phase` 실행 +- 페이즈 검증 필요 → `/gsd-verify-work` 실행 +- 모든 페이즈 완료 → `/gsd-complete-milestone` 제안 + +```bash +/gsd-next # 다음 단계 자동 감지 및 실행 +``` + +--- + +### `/gsd-session-report` + +작업 요약, 결과, 예상 리소스 사용량을 포함한 세션 보고서를 생성합니다. + +**사전 조건:** 최근 작업이 있는 활성 프로젝트 +**생성 파일:** `.planning/reports/SESSION_REPORT.md` + +```bash +/gsd-session-report # 세션 종료 후 요약 생성 +``` + +**보고서 포함 내용.** +- 수행된 작업 (커밋, 실행된 계획, 진행된 페이즈) +- 결과 및 산출물 +- 블로커 및 결정 사항 +- 예상 토큰/비용 사용량 +- 다음 단계 권장사항 + +--- + +### `/gsd-ship` + +완료된 페이즈 작업으로부터 자동 생성된 본문이 포함된 PR을 만듭니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `N` | 아니오 | 페이즈 번호 또는 마일스톤 버전 (예: `4` 또는 `v1.0`) | +| `--draft` | 아니오 | 초안 PR로 생성합니다 | + +**사전 조건:** 페이즈 검증 완료 (`/gsd-verify-work` 통과), `gh` CLI 설치 및 인증 +**생성 파일:** 계획 아티팩트 기반의 풍부한 본문이 포함된 GitHub PR, STATE.md 업데이트 + +```bash +/gsd-ship 4 # 페이즈 4 출시 +/gsd-ship 4 --draft # 초안 PR로 출시 +``` + +**PR 본문 포함 내용.** +- ROADMAP.md의 페이즈 목표 +- SUMMARY.md 파일의 변경사항 요약 +- 처리된 요구사항 (REQ-ID) +- 검증 상태 +- 핵심 결정사항 + +--- + +### `/gsd-ui-review` + +구현된 프론트엔드의 6개 기둥 기반 시각적 감사를 소급하여 수행합니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `N` | 아니오 | 페이즈 번호 (기본값: 마지막 실행된 페이즈) | + +**사전 조건:** 프론트엔드 코드가 있는 프로젝트 (독립 실행 가능, GSD 프로젝트 불필요) +**생성 파일:** `{phase}-UI-REVIEW.md`, `.planning/ui-reviews/`에 스크린샷 + +```bash +/gsd-ui-review # 현재 페이즈 감사 +/gsd-ui-review 3 # 페이즈 3 감사 +``` + +--- + +### `/gsd-audit-uat` + +모든 미완료 UAT 및 검증 항목에 대한 교차 페이즈 감사를 수행합니다. + +**사전 조건:** UAT 또는 검증이 포함된 페이즈가 하나 이상 실행되어 있어야 합니다. +**생성 파일:** 사람이 직접 수행하는 테스트 계획이 포함된 분류된 감사 보고서 + +```bash +/gsd-audit-uat +``` + +--- + +### `/gsd-audit-milestone` + +마일스톤이 완료 정의를 충족했는지 검증합니다. + +**사전 조건:** 모든 페이즈가 실행되어 있어야 합니다. +**생성 파일:** 갭 분석이 포함된 감사 보고서 + +```bash +/gsd-audit-milestone +``` + +--- + +### `/gsd-complete-milestone` + +마일스톤을 아카이브하고 릴리스 태그를 생성합니다. + +**사전 조건:** 마일스톤 감사 완료 권장 +**생성 파일:** `MILESTONES.md` 항목, git 태그 + +```bash +/gsd-complete-milestone +``` + +--- + +### `/gsd-milestone-summary` + +팀 온보딩 및 리뷰를 위해 마일스톤 아티팩트로부터 포괄적인 프로젝트 요약을 생성합니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `version` | 아니오 | 마일스톤 버전 (기본값: 현재/최신 마일스톤) | + +**사전 조건:** 완료되었거나 진행 중인 마일스톤이 하나 이상 있어야 합니다. +**생성 파일:** `.planning/reports/MILESTONE_SUMMARY-v{version}.md` + +**요약 포함 내용.** +- 개요, 아키텍처 결정사항, 페이즈별 분석 +- 핵심 결정사항 및 트레이드오프 +- 요구사항 충족 현황 +- 기술 부채 및 지연 항목 +- 신규 팀원을 위한 시작 가이드 +- 생성 후 대화형 Q&A 제공 + +```bash +/gsd-milestone-summary # 현재 마일스톤 요약 +/gsd-milestone-summary v1.0 # 특정 마일스톤 요약 +``` + +--- + +### `/gsd-new-milestone` + +다음 버전 사이클을 시작합니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `name` | 아니오 | 마일스톤 이름 | +| `--reset-phase-numbers` | 아니오 | 새 마일스톤을 Phase 1부터 시작하고 로드맵 작업 전에 기존 페이즈 디렉터리를 아카이브합니다 | + +**사전 조건:** 이전 마일스톤이 완료되어 있어야 합니다. +**생성 파일:** 업데이트된 `PROJECT.md`, 새 `REQUIREMENTS.md`, 새 `ROADMAP.md` + +```bash +/gsd-new-milestone # 대화형 모드 +/gsd-new-milestone "v2.0 Mobile" # 이름이 지정된 마일스톤 +/gsd-new-milestone --reset-phase-numbers "v2.0 Mobile" # 마일스톤 번호를 1부터 재시작 +``` + +--- + +## 페이즈 관리 명령어 + +### `/gsd-add-phase` + +로드맵에 새 페이즈를 추가합니다. + +```bash +/gsd-add-phase # 대화형 — 페이즈를 설명합니다 +``` + +### `/gsd-insert-phase` + +소수점 번호 체계를 사용하여 페이즈 사이에 긴급 작업을 삽입합니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `N` | 아니오 | 이 페이즈 번호 다음에 삽입합니다 | + +```bash +/gsd-insert-phase 3 # 페이즈 3과 4 사이에 삽입 → 3.1 생성 +``` + +### `/gsd-remove-phase` + +미래 페이즈를 제거하고 이후 페이즈 번호를 재정렬합니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `N` | 아니오 | 제거할 페이즈 번호 | + +```bash +/gsd-remove-phase 7 # 페이즈 7 제거, 8→7, 9→8 등으로 재번호 +``` + +### `/gsd-list-phase-assumptions` + +계획 수립 전 OpenCode의 예상 접근 방식을 미리 확인합니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `N` | 아니오 | 페이즈 번호 | + +```bash +/gsd-list-phase-assumptions 2 # 페이즈 2 가정 사항 확인 +``` + +### `/gsd-plan-milestone-gaps` + +마일스톤 감사에서 발견된 갭을 보완하는 페이즈를 생성합니다. + +```bash +/gsd-plan-milestone-gaps # 각 감사 갭에 대한 페이즈 생성 +``` + +### `/gsd-research-phase` + +심층 에코시스템 조사만 수행합니다 (독립 실행 — 일반적으로 `/gsd-plan-phase`를 사용하세요). + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `N` | 아니오 | 페이즈 번호 | + +```bash +/gsd-research-phase 4 # 페이즈 4 도메인 조사 +``` + +### `/gsd-validate-phase` + +Nyquist 검증 갭을 소급하여 감사하고 보완합니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `N` | 아니오 | 페이즈 번호 | + +```bash +/gsd-validate-phase 2 # 페이즈 2 테스트 커버리지 감사 +``` + +--- + +## 탐색 명령어 + +### `/gsd-progress` + +상태와 다음 단계를 표시합니다. + +```bash +/gsd-progress # "지금 어디 있나? 다음은 무엇인가?" +``` + +### `/gsd-resume-work` + +마지막 세션의 전체 컨텍스트를 복원합니다. + +```bash +/gsd-resume-work # 컨텍스트 초기화 또는 새 세션 후 실행 +``` + +### `/gsd-pause-work` + +페이즈 중간에 중단할 때 컨텍스트 핸드오프를 저장합니다. + +```bash +/gsd-pause-work # continue-here.md 생성 +``` + +### `/gsd-manager` + +하나의 터미널에서 여러 페이즈를 관리하는 대화형 명령 센터입니다. + +**사전 조건:** `.planning/ROADMAP.md`가 존재해야 합니다. +**동작 방식.** +- 시각적 상태 표시기가 포함된 모든 페이즈 대시보드 +- 의존성과 진행 상황에 따른 최적 다음 작업 추천 +- 작업 디스패치: discuss는 인라인으로 실행되고 plan/execute는 백그라운드 에이전트로 실행됩니다 +- 하나의 터미널에서 여러 페이즈를 병렬로 처리하는 파워 유저를 위해 설계되었습니다 + +```bash +/gsd-manager # 명령 센터 대시보드 열기 +``` + +--- + +### `/gsd-help` + +모든 명령어와 사용 가이드를 표시합니다. + +```bash +/gsd-help # 빠른 레퍼런스 +``` + +--- + +## 유틸리티 명령어 + +### `/gsd-quick` + +GSD 보증을 갖춘 임시 작업을 실행합니다. + +| 플래그 | 설명 | +|--------|------| +| `--full` | 계획 검사 (2회 반복) + 실행 후 검증 활성화 | +| `--discuss` | 경량 사전 계획 토론 | +| `--research` | 계획 전 집중 조사자 스폰 | + +플래그는 조합하여 사용할 수 있습니다. + +```bash +/gsd-quick # 기본 빠른 작업 +/gsd-quick --discuss --research # 토론 + 조사 + 계획 +/gsd-quick --full # 계획 검사 및 검증 포함 +/gsd-quick --discuss --research --full # 모든 선택적 단계 포함 +``` + +### `/gsd-autonomous` + +남은 모든 페이즈를 자율적으로 실행합니다. + +| 플래그 | 설명 | +|--------|------| +| `--from N` | 특정 페이즈 번호부터 시작합니다 | + +```bash +/gsd-autonomous # 남은 모든 페이즈 실행 +/gsd-autonomous --from 3 # 페이즈 3부터 시작 +``` + +### `/gsd-do` + +자유 형식 텍스트를 적절한 GSD 명령어로 라우팅합니다. + +```bash +/gsd-do # 원하는 작업을 설명합니다 +``` + +### `/gsd-note` + +마찰 없는 아이디어 캡처 — 노트 추가, 목록 조회, 또는 노트를 할 일로 승격합니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `text` | 아니오 | 캡처할 노트 텍스트 (기본값: 추가 모드) | +| `list` | 아니오 | 프로젝트 및 전역 범위의 모든 노트 목록 | +| `promote N` | 아니오 | N번 노트를 구조화된 할 일로 변환 | + +| 플래그 | 설명 | +|--------|------| +| `--global` | 노트 작업에 전역 범위 사용 | + +```bash +/gsd-note "Consider caching strategy for API responses" +/gsd-note list +/gsd-note promote 3 +``` + +### `/gsd-debug` + +지속적인 상태를 유지하는 체계적인 디버깅을 수행합니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `description` | 아니오 | 버그 설명 | + +```bash +/gsd-debug "Login button not responding on mobile Safari" +``` + +### `/gsd-add-todo` + +나중을 위한 아이디어나 작업을 캡처합니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `description` | 아니오 | 할 일 설명 | + +```bash +/gsd-add-todo "Consider adding dark mode support" +``` + +### `/gsd-check-todos` + +보류 중인 할 일 목록을 표시하고 작업할 항목을 선택합니다. + +```bash +/gsd-check-todos +``` + +### `/gsd-add-tests` + +완료된 페이즈에 대한 테스트를 생성합니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `N` | 아니오 | 페이즈 번호 | + +```bash +/gsd-add-tests 2 # 페이즈 2 테스트 생성 +``` + +### `/gsd-stats` + +프로젝트 통계를 표시합니다. + +```bash +/gsd-stats # 프로젝트 지표 대시보드 +``` + +### `/gsd-profile-user` + +OpenCode 세션 분석을 통해 8개 차원(커뮤니케이션 스타일, 의사결정 패턴, 디버깅 접근 방식, UX 선호도, 벤더 선택, 불만 유발 요인, 학습 스타일, 설명 깊이)으로 개발자 행동 프로필을 생성합니다. OpenCode의 응답을 개인화하는 아티팩트를 생성합니다. + +| 플래그 | 설명 | +|--------|------| +| `--questionnaire` | 세션 분석 대신 대화형 설문지를 사용합니다 | +| `--refresh` | 세션을 재분석하고 프로필을 재생성합니다 | + +**생성 아티팩트.** +- `USER-PROFILE.md` — 전체 행동 프로필 +- `/gsd-dev-preferences` 명령어 — 모든 세션에서 선호도를 로드합니다 +- `AGENTS.md` 프로필 섹션 — OpenCode에 의해 자동으로 인식됩니다 + +```bash +/gsd-profile-user # 세션 분석 및 프로필 구축 +/gsd-profile-user --questionnaire # 대화형 설문지 대체 방법 +/gsd-profile-user --refresh # 새로운 분석으로 재생성 +``` + +### `/gsd-health` + +`.planning/` 디렉터리의 무결성을 검사합니다. + +| 플래그 | 설명 | +|--------|------| +| `--repair` | 복구 가능한 문제를 자동으로 수정합니다 | + +```bash +/gsd-health # 무결성 검사 +/gsd-health --repair # 검사 및 수정 +``` + +### `/gsd-cleanup` + +완료된 마일스톤의 누적된 페이즈 디렉터리를 아카이브합니다. + +```bash +/gsd-cleanup +``` + +--- + +## 진단 명령어 + +### `/gsd-forensics` + +실패하거나 멈춘 GSD 워크플로우에 대한 사후 조사를 수행합니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `description` | 아니오 | 문제 설명 (생략 시 프롬프트로 입력) | + +**사전 조건:** `.planning/` 디렉터리가 존재해야 합니다. +**생성 파일:** `.planning/forensics/report-{timestamp}.md` + +**조사 항목.** +- Git 히스토리 분석 (최근 커밋, 멈춤 패턴, 시간 간격) +- 아티팩트 무결성 (완료된 페이즈에 대한 예상 파일) +- STATE.md 이상 및 세션 히스토리 +- 커밋되지 않은 작업, 충돌, 방치된 변경사항 +- 최소 4가지 이상 유형 검사 (멈춤 루프, 누락된 아티팩트, 방치된 작업, 충돌/중단) +- 실행 가능한 발견사항이 있으면 GitHub 이슈 생성 제안 + +```bash +/gsd-forensics # 대화형 — 문제 입력 프롬프트 +/gsd-forensics "Phase 3 execution stalled" # 문제 설명과 함께 실행 +``` + +--- + +## 워크스트림 관리 + +### `/gsd-workstreams` + +마일스톤의 서로 다른 영역에 대한 동시 작업을 위한 병렬 워크스트림을 관리합니다. + +**서브커맨드.** + +| 서브커맨드 | 설명 | +|------------|------| +| `list` | 상태와 함께 모든 워크스트림 목록 (서브커맨드 없을 경우 기본값) | +| `create ` | 새 워크스트림 생성 | +| `status ` | 특정 워크스트림의 상세 상태 | +| `switch ` | 활성 워크스트림 설정 | +| `progress` | 모든 워크스트림의 진행 상황 요약 | +| `complete ` | 완료된 워크스트림 아카이브 | +| `resume ` | 워크스트림의 작업 재개 | + +**사전 조건:** 활성 GSD 프로젝트 +**생성 파일:** `.planning/` 하위의 워크스트림 디렉터리, 워크스트림별 상태 추적 + +```bash +/gsd-workstreams # 모든 워크스트림 목록 +/gsd-workstreams create backend-api # 새 워크스트림 생성 +/gsd-workstreams switch backend-api # 활성 워크스트림 설정 +/gsd-workstreams status backend-api # 상세 상태 확인 +/gsd-workstreams progress # 교차 워크스트림 진행 상황 개요 +/gsd-workstreams complete backend-api # 완료된 워크스트림 아카이브 +/gsd-workstreams resume backend-api # 워크스트림 작업 재개 +``` + +--- + +## 설정 명령어 + +### `/gsd-settings` + +워크플로우 토글 및 모델 프로필의 대화형 설정을 합니다. + +```bash +/gsd-settings # 대화형 설정 +``` + +### `/gsd-set-profile` + +프로필을 빠르게 전환합니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `profile` | **예** | `quality`, `balanced`, `budget`, 또는 `inherit` | + +```bash +/gsd-set-profile budget # 예산 프로필로 전환 +/gsd-set-profile quality # 품질 프로필로 전환 +``` + +--- + +## 브라운필드 명령어 + +### `/gsd-map-codebase` + +병렬 매퍼 에이전트를 사용하여 기존 코드베이스를 분석합니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `area` | 아니오 | 특정 영역으로 매핑 범위를 제한합니다 | + +```bash +/gsd-map-codebase # 전체 코드베이스 분석 +/gsd-map-codebase auth # 인증 영역에 집중 +``` + +--- + +## 업데이트 명령어 + +### `/gsd-update` + +변경 로그 미리보기와 함께 GSD를 업데이트합니다. + +```bash +/gsd-update # 업데이트 확인 및 설치 +``` + +### `/gsd-reapply-patches` + +GSD 업데이트 후 로컬 수정사항을 복원합니다. + +```bash +/gsd-reapply-patches # 로컬 변경사항 병합 +``` + +--- + +## 빠른 인라인 명령어 + +### `/gsd-fast` + +서브에이전트나 계획 오버헤드 없이 간단한 작업을 인라인으로 실행합니다. 오타 수정, 설정 변경, 소규모 리팩터링, 누락된 커밋에 적합합니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `task description` | 아니오 | 수행할 작업 (생략 시 프롬프트로 입력) | + +**`/gsd-quick`의 대체가 아닙니다.** 조사, 다단계 계획 또는 검증이 필요한 작업에는 `/gsd-quick`을 사용하세요. + +```bash +/gsd-fast "fix typo in README" +/gsd-fast "add .env to gitignore" +``` + +--- + +## 코드 품질 명령어 + +### `/gsd-review` + +외부 AI CLI를 통한 페이즈 계획의 교차 AI 동료 리뷰를 수행합니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `--phase N` | **예** | 리뷰할 페이즈 번호 | + +| 플래그 | 설명 | +|--------|------| +| `--gemini` | Gemini CLI 리뷰 포함 | +| `--OpenCode` | OpenCode CLI 리뷰 포함 (별도 세션) | +| `--codex` | Codex CLI 리뷰 포함 | +| `--all` | 사용 가능한 모든 CLI 포함 | + +**생성 파일:** `{phase}-REVIEWS.md` — `/gsd-plan-phase --reviews`에서 사용 가능 + +```bash +/gsd-review --phase 3 --all +/gsd-review --phase 2 --gemini +``` + +--- + +### `/gsd-pr-branch` + +`.planning/` 커밋을 필터링한 깔끔한 PR 브랜치를 생성합니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `target branch` | 아니오 | 기본 브랜치 (기본값: `main`) | + +**목적:** 리뷰어에게 GSD 계획 아티팩트가 아닌 코드 변경사항만 표시합니다. + +```bash +/gsd-pr-branch # main을 기준으로 필터링 +/gsd-pr-branch develop # develop을 기준으로 필터링 +``` + +--- + +### `/gsd-audit-uat` + +모든 미완료 UAT 및 검증 항목에 대한 교차 페이즈 감사를 수행합니다. + +**사전 조건:** UAT 또는 검증이 포함된 페이즈가 하나 이상 실행되어 있어야 합니다. +**생성 파일:** 사람이 직접 수행하는 테스트 계획이 포함된 분류된 감사 보고서 + +```bash +/gsd-audit-uat +``` + +--- + +## 백로그 및 스레드 명령어 + +### `/gsd-add-backlog` + +999.x 번호 체계를 사용하여 백로그 파킹 롯에 아이디어를 추가합니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `description` | **예** | 백로그 항목 설명 | + +**999.x 번호 체계**는 백로그 항목을 활성 페이즈 순서 밖에 유지합니다. 페이즈 디렉터리가 즉시 생성되므로 해당 항목에 대해 `/gsd-discuss-phase`와 `/gsd-plan-phase`를 사용할 수 있습니다. + +```bash +/gsd-add-backlog "GraphQL API layer" +/gsd-add-backlog "Mobile responsive redesign" +``` + +--- + +### `/gsd-review-backlog` + +백로그 항목을 검토하고 활성 마일스톤으로 승격합니다. + +**항목별 작업:** 승격 (활성 순서로 이동), 유지 (백로그에 남김), 제거 (삭제). + +```bash +/gsd-review-backlog +``` + +--- + +### `/gsd-plant-seed` + +트리거 조건이 있는 미래 지향적인 아이디어를 캡처합니다. 적절한 마일스톤 시점에 자동으로 표면화됩니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| `idea summary` | 아니오 | 시드 설명 (생략 시 프롬프트로 입력) | + +시드는 컨텍스트 부식 문제를 해결합니다. 아무도 읽지 않는 Deferred의 한 줄짜리 메모 대신, 시드는 전체 WHY, 언제 표면화할지, 세부 내용에 대한 단서를 보존합니다. + +**생성 파일:** `.planning/seeds/SEED-NNN-slug.md` +**사용처:** `/gsd-new-milestone` (시드를 스캔하여 일치 항목 제시) + +```bash +/gsd-plant-seed "Add real-time collaboration when WebSocket infra is in place" +``` + +--- + +### `/gsd-thread` + +교차 세션 작업을 위한 지속적인 컨텍스트 스레드를 관리합니다. + +| 인수 | 필수 여부 | 설명 | +|------|----------|------| +| (없음) | — | 모든 스레드 목록 | +| `name` | — | 이름으로 기존 스레드 재개 | +| `description` | — | 새 스레드 생성 | + +스레드는 여러 세션에 걸쳐 이어지지만 특정 페이즈에 속하지 않는 작업을 위한 경량 교차 세션 지식 저장소입니다. `/gsd-pause-work`보다 가볍습니다. + +```bash +/gsd-thread # 모든 스레드 목록 +/gsd-thread fix-deploy-key-auth # 스레드 재개 +/gsd-thread "Investigate TCP timeout in pasta service" # 새 스레드 생성 +``` + +--- + +## 커뮤니티 명령어 + +### `/gsd-join-discord` + +Discord 커뮤니티 초대 링크를 엽니다. + +```bash +/gsd-join-discord +``` diff --git a/gsd-opencode/docs/ko-KR/CONFIGURATION.md b/gsd-opencode/docs/ko-KR/CONFIGURATION.md new file mode 100644 index 0000000..3884876 --- /dev/null +++ b/gsd-opencode/docs/ko-KR/CONFIGURATION.md @@ -0,0 +1,342 @@ +# GSD 설정 레퍼런스 + +> 전체 설정 스키마, 워크플로우 토글, 모델 프로필, git 브랜칭 옵션입니다. 기능에 대한 맥락은 [Feature Reference](FEATURES.md)를 참조하세요. + +--- + +## 설정 파일 + +GSD는 프로젝트 설정을 `.planning/config.json`에 저장합니다. `/gsd-new-project` 실행 시 생성되며 `/gsd-settings`를 통해 업데이트할 수 있습니다. + +### 전체 스키마 + +```json +{ + "mode": "interactive", + "granularity": "standard", + "model_profile": "balanced", + "model_overrides": {}, + "planning": { + "commit_docs": true, + "search_gitignored": false + }, + "workflow": { + "research": true, + "plan_check": true, + "verifier": true, + "auto_advance": false, + "nyquist_validation": true, + "ui_phase": true, + "ui_safety_gate": true, + "node_repair": true, + "node_repair_budget": 2, + "research_before_questions": false, + "discuss_mode": "discuss", + "skip_discuss": false, + "text_mode": false + }, + "hooks": { + "context_warnings": true, + "workflow_guard": false + }, + "parallelization": { + "enabled": true, + "plan_level": true, + "task_level": false, + "skip_checkpoints": true, + "max_concurrent_agents": 3, + "min_plans_for_parallel": 2 + }, + "git": { + "branching_strategy": "none", + "phase_branch_template": "gsd/phase-{phase}-{slug}", + "milestone_branch_template": "gsd/{milestone}-{slug}", + "quick_branch_template": null + }, + "gates": { + "confirm_project": true, + "confirm_phases": true, + "confirm_roadmap": true, + "confirm_breakdown": true, + "confirm_plan": true, + "execute_next_plan": true, + "issues_review": true, + "confirm_transition": true + }, + "safety": { + "always_confirm_destructive": true, + "always_confirm_external_services": true + } +} +``` + +--- + +## 핵심 설정 + +| 설정 | 타입 | 옵션 | 기본값 | 설명 | +|------|------|------|--------|------| +| `mode` | enum | `interactive`, `yolo` | `interactive` | `yolo`는 결정을 자동 승인하고 `interactive`는 각 단계에서 확인을 요청합니다. | +| `granularity` | enum | `coarse`, `standard`, `fine` | `standard` | 단계 수를 조절합니다. `coarse` (3~5), `standard` (5~8), `fine` (8~12) | +| `model_profile` | enum | `quality`, `balanced`, `budget`, `inherit` | `balanced` | 각 에이전트의 모델 티어입니다. ([Model Profiles](#model-profiles) 참조) | + +> **참고:** `granularity`는 v1.22.3에서 `depth`에서 이름이 변경되었습니다. 기존 설정은 자동으로 마이그레이션됩니다. + +--- + +## 워크플로우 토글 + +모든 워크플로우 토글은 **키가 없으면 활성화** 패턴을 따릅니다. 설정에서 키가 없으면 기본값은 `true`입니다. + +| 설정 | 타입 | 기본값 | 설명 | +|------|------|--------|------| +| `workflow.research` | boolean | `true` | 각 단계 플래닝 전 도메인 조사 | +| `workflow.plan_check` | boolean | `true` | 플랜 검증 루프 (최대 3회 반복) | +| `workflow.verifier` | boolean | `true` | 실행 후 단계 목표 대비 검증 | +| `workflow.auto_advance` | boolean | `false` | discuss → plan → execute를 중단 없이 자동으로 연결 | +| `workflow.nyquist_validation` | boolean | `true` | plan 단계 리서치 중 테스트 커버리지 매핑 | +| `workflow.ui_phase` | boolean | `true` | 프론트엔드 단계를 위한 UI 디자인 계약서 생성 | +| `workflow.ui_safety_gate` | boolean | `true` | plan 단계에서 프론트엔드 단계에 대해 /gsd-ui-phase 실행 여부 확인 | +| `workflow.node_repair` | boolean | `true` | 검증 실패 시 자율적 태스크 복구 | +| `workflow.node_repair_budget` | number | `2` | 실패한 태스크당 최대 복구 시도 횟수 | +| `workflow.research_before_questions` | boolean | `false` | 토론 질문 후가 아닌 전에 리서치 실행 | +| `workflow.discuss_mode` | string | `'discuss'` | `/gsd-discuss-phase`의 컨텍스트 수집 방식을 제어합니다. `'discuss'` (기본값)는 질문을 하나씩 합니다. `'assumptions'`는 코드베이스를 먼저 읽고 신뢰도 수준이 있는 구조화된 가정을 생성하여 틀린 부분만 수정하도록 요청합니다. v1.28에서 추가 | +| `workflow.skip_discuss` | boolean | `false` | `true`로 설정하면 `/gsd-autonomous`가 discuss 단계를 완전히 건너뛰고 ROADMAP 단계 목표로부터 최소한의 CONTEXT.md를 작성합니다. 개발자 선호사항이 PROJECT.md/REQUIREMENTS.md에 모두 캡처된 프로젝트에 유용합니다. v1.28에서 추가 | +| `workflow.text_mode` | boolean | `false` | question TUI 메뉴를 일반 텍스트 번호 목록으로 대체합니다. TUI 메뉴가 렌더링되지 않는 OpenCode 원격 세션 (`/rc` 모드)에 필요합니다. discuss 단계에서 `--text` 플래그로 세션별 설정도 가능합니다. v1.28에서 추가 | + +### 권장 프리셋 + +| 시나리오 | mode | granularity | profile | research | plan_check | verifier | +|---------|------|-------------|---------|----------|------------|----------| +| 프로토타이핑 | `yolo` | `coarse` | `budget` | `false` | `false` | `false` | +| 일반 개발 | `interactive` | `standard` | `balanced` | `true` | `true` | `true` | +| 프로덕션 릴리스 | `interactive` | `fine` | `quality` | `true` | `true` | `true` | + +--- + +## 플래닝 설정 + +| 설정 | 타입 | 기본값 | 설명 | +|------|------|--------|------| +| `planning.commit_docs` | boolean | `true` | `.planning/` 파일을 git에 커밋할지 여부 | +| `planning.search_gitignored` | boolean | `false` | 광범위한 검색에 `--no-ignore`를 추가하여 `.planning/`을 포함 | + +### 자동 감지 + +`.planning/`이 `.gitignore`에 포함되어 있으면 config.json 설정과 무관하게 `commit_docs`가 자동으로 `false`로 설정됩니다. 이는 git 오류를 방지합니다. + +--- + +## 훅 설정 + +| 설정 | 타입 | 기본값 | 설명 | +|------|------|--------|------| +| `hooks.context_warnings` | boolean | `true` | context monitor 훅을 통해 컨텍스트 윈도우 사용 경고 표시 | +| `hooks.workflow_guard` | boolean | `false` | GSD 워크플로우 컨텍스트 밖에서 파일 편집이 발생할 때 경고 ((`/gsd-quick` 또는 `/gsd-fast` 사용 권고)) | + +프롬프트 주입 방지 훅 (`gsd-prompt-guard.js`)은 항상 활성화되며 비활성화할 수 없습니다. 워크플로우 토글이 아닌 보안 기능입니다. + +### 플래닝 비공개 설정 + +플래닝 아티팩트를 git에서 제외하려면 다음과 같이 설정합니다. + +1. `planning.commit_docs: false` 및 `planning.search_gitignored: true` 설정 +2. `.planning/`을 `.gitignore`에 추가 +3. 이미 추적 중인 경우: `git rm -r --cached .planning/ && git commit -m "chore: stop tracking planning docs"` + +--- + +## 병렬화 설정 + +| 설정 | 타입 | 기본값 | 설명 | +|------|------|--------|------| +| `parallelization.enabled` | boolean | `true` | 독립적인 플랜을 동시에 실행 | +| `parallelization.plan_level` | boolean | `true` | 플랜 수준에서 병렬화 | +| `parallelization.task_level` | boolean | `false` | 플랜 내 태스크를 병렬화 | +| `parallelization.skip_checkpoints` | boolean | `true` | 병렬 실행 중 체크포인트 건너뜀 | +| `parallelization.max_concurrent_agents` | number | `3` | 동시 실행 가능한 최대 에이전트 수 | +| `parallelization.min_plans_for_parallel` | number | `2` | 병렬 실행을 시작하기 위한 최소 플랜 수 | + +> **Pre-commit 훅과 병렬 실행:** 병렬화가 활성화되면 executor 에이전트는 빌드 잠금 경합(예: Rust 프로젝트의 cargo lock 충돌)을 피하기 위해 `--no-verify`로 커밋합니다. 오케스트레이터는 각 wave가 완료된 후 훅을 한 번 검증합니다. STATE.md 쓰기는 동시 쓰기 충돌을 방지하기 위해 파일 수준 잠금으로 보호됩니다. 커밋마다 훅을 실행해야 한다면 `parallelization.enabled: false`로 설정하세요. + +--- + +## Git 브랜칭 + +| 설정 | 타입 | 기본값 | 설명 | +|------|------|--------|------| +| `git.branching_strategy` | enum | `none` | `none`, `phase`, 또는 `milestone` | +| `git.phase_branch_template` | string | `gsd/phase-{phase}-{slug}` | phase 전략의 브랜치 이름 템플릿 | +| `git.milestone_branch_template` | string | `gsd/{milestone}-{slug}` | milestone 전략의 브랜치 이름 템플릿 | +| `git.quick_branch_template` | string 또는 null | `null` | `/gsd-quick` 태스크를 위한 선택적 브랜치 이름 템플릿 | + +### 전략 비교 + +| 전략 | 브랜치 생성 | 범위 | 병합 시점 | 적합한 경우 | +|------|------------|------|----------|------------| +| `none` | 없음 | 해당 없음 | 해당 없음 | 개인 개발, 단순 프로젝트 | +| `phase` | `execute-phase` 시작 시 | 단일 단계 | 단계 완료 후 사용자가 병합 | 단계별 코드 리뷰, 세밀한 롤백 | +| `milestone` | 첫 번째 `execute-phase` 시 | milestone 내 모든 단계 | `complete-milestone` 시 | 릴리스 브랜치, 버전별 PR | + +### 템플릿 변수 + +| 변수 | 사용 가능한 템플릿 | 예시 | +|------|------------------|------| +| `{phase}` | `phase_branch_template` | `03` (0 패딩) | +| `{slug}` | 두 템플릿 모두 | `user-authentication` (소문자, 하이픈) | +| `{milestone}` | `milestone_branch_template` | `v1.0` | +| `{num}` / `{quick}` | `quick_branch_template` | `260317-abc` (quick 태스크 ID) | + +quick 태스크 브랜칭 예시: + +```json +"git": { + "quick_branch_template": "gsd/quick-{num}-{slug}" +} +``` + +### Milestone 완료 시 병합 옵션 + +| 옵션 | Git 명령어 | 결과 | +|------|-----------|------| +| Squash merge (권장) | `git merge --squash` | 브랜치당 단일 클린 커밋 | +| Merge with history | `git merge --no-ff` | 모든 개별 커밋 보존 | +| Delete without merging | `git branch -D` | 브랜치 작업 폐기 | +| Keep branches | (없음) | 나중에 수동으로 처리 | + +--- + +## Gate 설정 + +워크플로우 중 확인 프롬프트를 제어합니다. + +| 설정 | 타입 | 기본값 | 설명 | +|------|------|--------|------| +| `gates.confirm_project` | boolean | `true` | 확정 전 프로젝트 세부사항 확인 | +| `gates.confirm_phases` | boolean | `true` | 단계 분류 확인 | +| `gates.confirm_roadmap` | boolean | `true` | 진행 전 로드맵 확인 | +| `gates.confirm_breakdown` | boolean | `true` | 태스크 분류 확인 | +| `gates.confirm_plan` | boolean | `true` | 실행 전 각 플랜 확인 | +| `gates.execute_next_plan` | boolean | `true` | 다음 플랜 실행 전 확인 | +| `gates.issues_review` | boolean | `true` | 수정 플랜 생성 전 이슈 검토 | +| `gates.confirm_transition` | boolean | `true` | 단계 전환 확인 | + +--- + +## 안전성 설정 + +| 설정 | 타입 | 기본값 | 설명 | +|------|------|--------|------| +| `safety.always_confirm_destructive` | boolean | `true` | 파괴적 작업(삭제, 덮어쓰기) 확인 | +| `safety.always_confirm_external_services` | boolean | `true` | 외부 서비스 상호작용 확인 | + +--- + +## 훅 설정 + +| 설정 | 타입 | 기본값 | 설명 | +|------|------|--------|------| +| `hooks.context_warnings` | boolean | `true` | 세션 중 컨텍스트 윈도우 사용 경고 표시 | + +--- + +## 모델 프로필 + +### 프로필 정의 + +| 에이전트 | `quality` | `balanced` | `budget` | `inherit` | +|---------|-----------|------------|----------|-----------| +| gsd-planner | Opus | Opus | Sonnet | Inherit | +| gsd-roadmapper | Opus | Sonnet | Sonnet | Inherit | +| gsd-executor | Opus | Sonnet | Sonnet | Inherit | +| gsd-phase-researcher | Opus | Sonnet | Haiku | Inherit | +| gsd-project-researcher | Opus | Sonnet | Haiku | Inherit | +| gsd-research-synthesizer | Sonnet | Sonnet | Haiku | Inherit | +| gsd-debugger | Opus | Sonnet | Sonnet | Inherit | +| gsd-codebase-mapper | Sonnet | Haiku | Haiku | Inherit | +| gsd-verifier | Sonnet | Sonnet | Haiku | Inherit | +| gsd-plan-checker | Sonnet | Sonnet | Haiku | Inherit | +| gsd-integration-checker | Sonnet | Sonnet | Haiku | Inherit | +| gsd-nyquist-auditor | Sonnet | Sonnet | Haiku | Inherit | + +### 에이전트별 재정의 + +전체 프로필을 변경하지 않고 특정 에이전트만 재정의할 수 있습니다. + +```json +{ + "model_profile": "balanced", + "model_overrides": { + "gsd-executor": "opus", + "gsd-planner": "haiku" + } +} +``` + +유효한 재정의 값: `opus`, `sonnet`, `haiku`, `inherit`, 또는 완전히 정규화된 모델 ID (예: `"openai/o3"`, `"google/gemini-2.5-pro"`). + +### 비 OpenCode 런타임 (Codex, OpenCode, Gemini CLI) + +비 OpenCode 런타임에 GSD를 설치하면 인스톨러가 자동으로 `~/.gsd/defaults.json`에 `resolve_model_ids: "omit"`을 설정합니다. 이로 인해 GSD는 모든 에이전트에 빈 model 파라미터를 반환하며 각 에이전트는 런타임에 설정된 모델을 사용합니다. 기본 사용 시 추가 설정은 필요하지 않습니다. + +에이전트마다 다른 모델을 사용하려면 런타임이 인식하는 완전히 정규화된 모델 ID로 `model_overrides`를 사용합니다. + +```json +{ + "resolve_model_ids": "omit", + "model_overrides": { + "gsd-planner": "o3", + "gsd-executor": "o4-mini", + "gsd-debugger": "o3", + "gsd-codebase-mapper": "o4-mini" + } +} +``` + +의도는 OpenCode 프로필 티어와 동일합니다. 추론 품질이 가장 중요한 플래닝과 디버깅에는 더 강력한 모델을 사용하고 플랜에 추론이 이미 포함된 실행과 매핑에는 저렴한 모델을 사용합니다. + +**접근 방식 선택 기준.** + +| 시나리오 | 설정 | 효과 | +|---------|------|------| +| 비 OpenCode 런타임, 단일 모델 | `resolve_model_ids: "omit"` (인스톨러 기본값) | 모든 에이전트가 런타임 기본 모델 사용 | +| 비 OpenCode 런타임, 계층형 모델 | `resolve_model_ids: "omit"` + `model_overrides` | 지정된 에이전트는 특정 모델 사용, 나머지는 런타임 기본값 사용 | +| OpenCode + OpenRouter/로컬 프로바이더 | `model_profile: "inherit"` | 모든 에이전트가 세션 모델을 따름 | +| OpenCode + OpenRouter, 계층형 | `model_profile: "inherit"` + `model_overrides` | 지정된 에이전트는 특정 모델 사용, 나머지는 상속 | + +**`resolve_model_ids` 값.** + +| 값 | 동작 | 사용 시점 | +|----|------|----------| +| `false` (기본값) | OpenCode 별칭 반환 (`opus`, `sonnet`, `haiku`) | 네이티브 Anthropic API를 사용하는 OpenCode | +| `true` | 별칭을 전체 OpenCode 모델 ID로 매핑 (`OpenCode-opus-4-0`) | 전체 ID가 필요한 API를 사용하는 OpenCode | +| `"omit"` | 빈 문자열 반환 (런타임이 기본값 선택) | 비 OpenCode 런타임 (Codex, OpenCode, Gemini CLI) | + +### 프로필 철학 + +| 프로필 | 철학 | 사용 시점 | +|--------|------|----------| +| `quality` | 모든 의사결정에 Opus, 검증에 Sonnet | 할당량 여유가 있을 때, 중요한 아키텍처 작업 | +| `balanced` | 플래닝에만 Opus, 나머지는 Sonnet | 일반 개발 (기본값) | +| `budget` | 코드 작성에 Sonnet, 리서치/검증에 Haiku | 대용량 작업, 덜 중요한 단계 | +| `inherit` | 모든 에이전트가 현재 세션 모델 사용 | 동적 모델 전환, **비 Anthropic 프로바이더** (OpenRouter, 로컬 모델) | + +--- + +## 환경 변수 + +| 변수 | 용도 | +|------|------| +| `CLAUDE_CONFIG_DIR` | 기본 설정 디렉토리 재정의 (`$HOME/.config/opencode/`) | +| `GEMINI_API_KEY` | context monitor가 훅 이벤트 이름을 전환하기 위해 감지 | +| `WSL_DISTRO_NAME` | 인스톨러가 WSL 경로 처리를 위해 감지 | + +--- + +## 전역 기본값 + +향후 프로젝트를 위한 전역 기본값으로 설정을 저장할 수 있습니다. + +**위치:** `~/.gsd/defaults.json` + +`/gsd-new-project`가 새 `config.json`을 생성할 때 전역 기본값을 읽어 초기 설정으로 병합합니다. 프로젝트별 설정은 항상 전역 설정보다 우선합니다. diff --git a/gsd-opencode/docs/ko-KR/FEATURES.md b/gsd-opencode/docs/ko-KR/FEATURES.md new file mode 100644 index 0000000..3e83c9e --- /dev/null +++ b/gsd-opencode/docs/ko-KR/FEATURES.md @@ -0,0 +1,1290 @@ +# GSD 기능 참조 + +> 기능 및 함수에 대한 완전한 문서와 요구사항입니다. 아키텍처 세부 사항은 [Architecture](ARCHITECTURE.md)를, 명령어 문법은 [Command Reference](COMMANDS.md)를 참조하세요. + +--- + +## 목차 + +- [핵심 기능](#core-features) + - [프로젝트 초기화](#1-project-initialization) + - [페이즈 논의](#2-phase-discussion) + - [UI 설계 계약](#3-ui-design-contract) + - [페이즈 계획](#4-phase-planning) + - [페이즈 실행](#5-phase-execution) + - [작업 검증](#6-work-verification) + - [UI 검토](#7-ui-review) + - [마일스톤 관리](#8-milestone-management) +- [계획 기능](#planning-features) + - [페이즈 관리](#9-phase-management) + - [빠른 모드](#10-quick-mode) + - [자율 모드](#11-autonomous-mode) + - [자유형 라우팅](#12-freeform-routing) + - [노트 캡처](#13-note-capture) + - [자동 진행(Next)](#14-auto-advance-next) +- [품질 보증 기능](#quality-assurance-features) + - [Nyquist 유효성 검사](#15-nyquist-validation) + - [계획 검사](#16-plan-checking) + - [실행 후 검증](#17-post-execution-verification) + - [노드 복구](#18-node-repair) + - [상태 유효성 검사](#19-health-validation) + - [교차 페이즈 회귀 게이트](#20-cross-phase-regression-gate) + - [요구사항 커버리지 게이트](#21-requirements-coverage-gate) +- [컨텍스트 엔지니어링 기능](#context-engineering-features) + - [컨텍스트 창 모니터링](#22-context-window-monitoring) + - [세션 관리](#23-session-management) + - [세션 보고](#24-session-reporting) + - [멀티 에이전트 오케스트레이션](#25-multi-agent-orchestration) + - [모델 프로파일](#26-model-profiles) +- [브라운필드 기능](#brownfield-features) + - [코드베이스 매핑](#27-codebase-mapping) +- [유틸리티 기능](#utility-features) + - [디버그 시스템](#28-debug-system) + - [할 일 관리](#29-todo-management) + - [통계 대시보드](#30-statistics-dashboard) + - [업데이트 시스템](#31-update-system) + - [설정 관리](#32-settings-management) + - [테스트 생성](#33-test-generation) +- [인프라 기능](#infrastructure-features) + - [Git 통합](#34-git-integration) + - [CLI 도구](#35-cli-tools) + - [멀티 런타임 지원](#36-multi-runtime-support) + - [훅 시스템](#37-hook-system) + - [개발자 프로파일링](#38-developer-profiling) + - [실행 강화](#39-execution-hardening) + - [검증 부채 추적](#40-verification-debt-tracking) +- [v1.27 기능](#v127-features) + - [빠른 모드(Fast Mode)](#41-fast-mode) + - [교차 AI 동료 검토](#42-cross-ai-peer-review) + - [백로그 주차장](#43-backlog-parking-lot) + - [지속적 컨텍스트 스레드](#44-persistent-context-threads) + - [PR 브랜치 필터링](#45-pr-branch-filtering) + - [보안 강화](#46-security-hardening) + - [멀티 저장소 워크스페이스 지원](#47-multi-repo-workspace-support) + - [논의 감사 추적](#48-discussion-audit-trail) +- [v1.28 기능](#v128-features) + - [포렌식](#49-forensics) + - [마일스톤 요약](#50-milestone-summary) + - [워크스트림 네임스페이싱](#51-workstream-namespacing) + - [매니저 대시보드](#52-manager-dashboard) + - [가정 논의 모드](#53-assumptions-discussion-mode) + - [UI 페이즈 자동 감지](#54-ui-phase-auto-detection) + - [멀티 런타임 설치 선택](#55-multi-runtime-installer-selection) + +--- + +## 핵심 기능 + +### 1. Project Initialization + +**명령어:** `/gsd-new-project [--auto @file.md]` + +**목적:** 사용자의 아이디어를 연구, 범위가 지정된 요구사항, 단계별 로드맵을 갖춘 완전히 구조화된 프로젝트로 전환합니다. + +**요구사항.** +- REQ-INIT-01: 프로젝트 범위가 완전히 파악될 때까지 적응형 질문을 진행해야 합니다. +- REQ-INIT-02: 도메인 생태계를 조사하는 병렬 연구 에이전트를 생성해야 합니다. +- REQ-INIT-03: 요구사항을 v1(필수), v2(향후), 범위 외 카테고리로 분류해야 합니다. +- REQ-INIT-04: 요구사항 추적성을 갖춘 단계별 로드맵을 생성해야 합니다. +- REQ-INIT-05: 진행 전에 사용자의 로드맵 승인을 요구해야 합니다. +- REQ-INIT-06: `.planning/PROJECT.md`가 이미 존재하는 경우 재초기화를 방지해야 합니다. +- REQ-INIT-07: 대화형 질문을 건너뛰고 문서에서 정보를 추출하는 `--auto @file.md` 플래그를 지원해야 합니다. + +**생성 산출물.** +| 산출물 | 설명 | +|----------|-------------| +| `PROJECT.md` | 프로젝트 비전, 제약조건, 기술적 결정, 발전 규칙 | +| `REQUIREMENTS.md` | 고유 ID(REQ-XX)가 있는 범위 지정 요구사항 | +| `ROADMAP.md` | 상태 추적 및 요구사항 매핑이 포함된 페이즈 분류 | +| `STATE.md` | 위치, 결정, 지표가 포함된 초기 프로젝트 상태 | +| `config.json` | 워크플로우 구성 | +| `research/SUMMARY.md` | 통합된 도메인 연구 결과 | +| `research/STACK.md` | 기술 스택 조사 | +| `research/FEATURES.md` | 기능 구현 패턴 | +| `research/ARCHITECTURE.md` | 아키텍처 패턴 및 트레이드오프 | +| `research/PITFALLS.md` | 일반적인 실패 모드와 완화 방법 | + +**프로세스.** +1. **질문** — "꿈 추출" 철학(요구사항 수집이 아닌)으로 안내되는 적응형 질문 +2. **연구** — 스택, 기능, 아키텍처, 위험 요소를 조사하는 4개의 병렬 연구자 에이전트 +3. **종합** — 연구 종합자가 결과를 SUMMARY.md로 통합 +4. **요구사항** — 사용자 응답과 연구에서 추출하여 범위별로 분류 +5. **로드맵** — 요구사항에 매핑된 페이즈 분류, 세분화 설정으로 페이즈 수 제어 + +**기능적 요구사항.** +- 감지된 프로젝트 유형(웹 앱, CLI, 모바일, API 등)에 따라 질문이 적응합니다. +- 연구 에이전트는 현재 생태계 정보를 위한 웹 검색 기능을 갖추고 있습니다. +- 세분화 설정으로 페이즈 수를 제어합니다. `coarse`(3-5), `standard`(5-8), `fine`(8-12) +- `--auto` 모드는 대화형 질문 없이 제공된 문서에서 모든 정보를 추출합니다. +- 기존 코드베이스 컨텍스트(`/gsd-map-codebase`에서)가 있으면 로드됩니다. + +--- + +### 2. Phase Discussion + +**명령어:** `/gsd-discuss-phase [N] [--auto] [--batch]` + +**목적:** 연구와 계획이 시작되기 전에 사용자의 구현 선호도와 결정을 캡처합니다. AI가 추측하게 만드는 회색 지대를 제거합니다. + +**요구사항.** +- REQ-DISC-01: 페이즈 범위를 분석하고 결정 영역(회색 지대)을 식별해야 합니다. +- REQ-DISC-02: 회색 지대를 유형별로 분류해야 합니다(시각적, API, 콘텐츠, 조직 등). +- REQ-DISC-03: 이전 CONTEXT.md 파일에서 이미 답변된 질문은 하지 않아야 합니다. +- REQ-DISC-04: 결정사항을 표준 참조와 함께 `{phase}-CONTEXT.md`에 저장해야 합니다. +- REQ-DISC-05: 권장 기본값을 자동 선택하는 `--auto` 플래그를 지원해야 합니다. +- REQ-DISC-06: 질문을 그룹으로 받는 `--batch` 플래그를 지원해야 합니다. +- REQ-DISC-07: 회색 지대를 식별하기 전에 관련 소스 파일을 스카우트해야 합니다(코드 인식 논의). + +**생성 산출물.** `{padded_phase}-CONTEXT.md` — 연구 및 계획에 반영되는 사용자 선호도 + +**회색 지대 카테고리.** +| 카테고리 | 결정 예시 | +|----------|-------------------| +| 시각적 기능 | 레이아웃, 밀도, 상호작용, 빈 상태 | +| API/CLI | 응답 형식, 플래그, 오류 처리, 상세 수준 | +| 콘텐츠 시스템 | 구조, 어조, 깊이, 흐름 | +| 조직 | 그룹화 기준, 명명, 중복, 예외 | + +--- + +### 3. UI Design Contract + +**명령어:** `/gsd-ui-phase [N]` + +**목적:** 계획 전에 설계 결정을 확정하여 페이즈 내 모든 컴포넌트가 일관된 시각적 기준을 공유하도록 합니다. + +**요구사항.** +- REQ-UI-01: 기존 디자인 시스템 상태를 감지해야 합니다(shadcn components.json, Tailwind config, 토큰). +- REQ-UI-02: 아직 답변되지 않은 설계 계약 질문만 물어봐야 합니다. +- REQ-UI-03: 6개 차원에 대해 유효성을 검사해야 합니다(Copywriting, Visuals, Color, Typography, Spacing, Registry Safety). +- REQ-UI-04: 유효성 검사가 BLOCKED를 반환하면 수정 루프에 진입해야 합니다(최대 2회 반복). +- REQ-UI-05: `components.json`이 없는 React/Next.js/Vite 프로젝트에 shadcn 초기화를 제공해야 합니다. +- REQ-UI-06: 서드파티 shadcn 레지스트리에 대한 레지스트리 안전 게이트를 적용해야 합니다. + +**생성 산출물.** `{padded_phase}-UI-SPEC.md` — 실행자가 사용하는 설계 계약 + +**6가지 유효성 검사 차원.** +1. **Copywriting** — CTA 레이블, 빈 상태, 오류 메시지 +2. **Visuals** — 초점, 시각적 계층구조, 아이콘 접근성 +3. **Color** — 강조색 사용 규율, 60/30/10 준수 +4. **Typography** — 글꼴 크기/굵기 제약 준수 +5. **Spacing** — 그리드 정렬, 토큰 일관성 +6. **Registry Safety** — 서드파티 컴포넌트 검사 요구사항 + +**shadcn 통합.** +- React/Next.js/Vite 프로젝트에서 누락된 `components.json`을 감지합니다. +- `ui.shadcn.com/create` 프리셋 구성을 통해 사용자를 안내합니다. +- 프리셋 문자열은 페이즈 간 재현 가능한 계획 산출물이 됩니다. +- 서드파티 컴포넌트 전에 `npx shadcn view`와 `npx shadcn diff`를 요구하는 안전 게이트가 있습니다. + +--- + +### 4. Phase Planning + +**명령어:** `/gsd-plan-phase [N] [--auto] [--skip-research] [--skip-verify]` + +**목적:** 구현 도메인을 연구하고 검증된 원자적 실행 계획을 생성합니다. + +**요구사항.** +- REQ-PLAN-01: 구현 접근 방식을 조사하는 페이즈 연구자를 생성해야 합니다. +- REQ-PLAN-02: 단일 컨텍스트 창에 맞는 2-3개 작업으로 구성된 계획을 생성해야 합니다. +- REQ-PLAN-03: `name`, `files`, `action`, `verify`, `done` 필드를 포함하는 `` 요소가 있는 XML 형식으로 계획을 구성해야 합니다. +- REQ-PLAN-04: 모든 계획에 `read_first`와 `acceptance_criteria` 섹션을 포함해야 합니다. +- REQ-PLAN-05: `--skip-verify`가 설정되지 않은 경우 계획 검사기 검증 루프를 실행해야 합니다(최대 3회 반복). +- REQ-PLAN-06: 연구 단계를 건너뛰는 `--skip-research` 플래그를 지원해야 합니다. +- REQ-PLAN-07: 프론트엔드 페이즈가 감지되고 UI-SPEC.md가 없는 경우 `/gsd-ui-phase` 실행을 촉구해야 합니다(UI 안전 게이트). +- REQ-PLAN-08: `workflow.nyquist_validation`이 활성화된 경우 Nyquist 유효성 검사 매핑을 포함해야 합니다. +- REQ-PLAN-09: 계획이 완료되기 전에 모든 페이즈 요구사항이 최소 하나의 계획에 포함되어 있는지 확인해야 합니다(요구사항 커버리지 게이트). + +**생성 산출물.** +| 산출물 | 설명 | +|----------|-------------| +| `{phase}-RESEARCH.md` | 생태계 연구 결과 | +| `{phase}-{N}-PLAN.md` | 원자적 실행 계획(각 2-3개 작업) | +| `{phase}-VALIDATION.md` | 테스트 커버리지 매핑(Nyquist 레이어) | + +**계획 구조(XML).** +```xml + + Create login endpoint + src/app/api/auth/login/route.ts + + Use jose for JWT. Validate credentials against users table. + Return httpOnly cookie on success. + + curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie + Valid credentials return cookie, invalid return 401 + +``` + +**계획 검사기 검증(8가지 차원).** +1. 요구사항 커버리지 — 계획이 모든 페이즈 요구사항을 다루는지 확인 +2. 작업 원자성 — 각 작업이 독립적으로 커밋 가능한지 확인 +3. 의존성 순서 — 작업이 올바른 순서로 배열되어 있는지 확인 +4. 파일 범위 — 계획 간 과도한 파일 중복이 없는지 확인 +5. 검증 명령어 — 각 작업에 테스트 가능한 완료 기준이 있는지 확인 +6. 컨텍스트 적합성 — 작업이 단일 컨텍스트 창에 맞는지 확인 +7. 갭 감지 — 누락된 구현 단계가 없는지 확인 +8. Nyquist 준수 — 작업에 자동화된 검증 명령어가 있는지 확인(활성화된 경우) + +--- + +### 5. Phase Execution + +**명령어:** `/gsd-execute-phase ` + +**목적:** 실행자별 새로운 컨텍스트 창을 사용한 웨이브 기반 병렬화로 페이즈의 모든 계획을 실행합니다. + +**요구사항.** +- REQ-EXEC-01: 계획 의존성을 분석하고 실행 웨이브로 그룹화해야 합니다. +- REQ-EXEC-02: 각 웨이브 내에서 독립적인 계획을 병렬로 생성해야 합니다. +- REQ-EXEC-03: 각 실행자에게 새로운 컨텍스트 창(200K 토큰)을 제공해야 합니다. +- REQ-EXEC-04: 작업별로 원자적 git 커밋을 생성해야 합니다. +- REQ-EXEC-05: 완료된 각 계획에 대한 SUMMARY.md를 생성해야 합니다. +- REQ-EXEC-06: 실행 후 검증자를 실행하여 페이즈 목표가 달성되었는지 확인해야 합니다. +- REQ-EXEC-07: git 브랜칭 전략을 지원해야 합니다(`none`, `phase`, `milestone`). +- REQ-EXEC-08: 작업 검증 실패 시 노드 복구 연산자를 호출해야 합니다(활성화된 경우). +- REQ-EXEC-09: 교차 페이즈 회귀를 감지하기 위해 검증 전에 이전 페이즈의 테스트 스위트를 실행해야 합니다. + +**생성 산출물.** +| 산출물 | 설명 | +|----------|-------------| +| `{phase}-{N}-SUMMARY.md` | 계획별 실행 결과 | +| `{phase}-VERIFICATION.md` | 실행 후 검증 보고서 | +| Git 커밋 | 작업별 원자적 커밋 | + +**웨이브 실행.** +- 의존성 없는 계획 → 웨이브 1(병렬) +- 웨이브 1에 의존하는 계획 → 웨이브 2(병렬, 웨이브 1 완료 후) +- 모든 계획이 완료될 때까지 계속 +- 파일 충돌로 인해 동일 웨이브 내 순차 실행 강제 + +**실행자 기능.** +- 전체 작업 지시사항이 담긴 PLAN.md 읽기 +- PROJECT.md, STATE.md, CONTEXT.md, RESEARCH.md에 접근 가능 +- 구조화된 커밋 메시지로 각 작업을 원자적으로 커밋 +- 병렬 실행 중 빌드 잠금 경쟁을 피하기 위해 커밋 시 `--no-verify` 사용 +- 체크포인트 유형 처리: `auto`, `checkpoint:human-verify`, `checkpoint:decision`, `checkpoint:human-action` +- SUMMARY.md에 계획과의 편차 보고 + +**병렬 안전성.** +- **Pre-commit 훅**: 병렬 에이전트가 건너뜀(`--no-verify`), 각 웨이브 후 오케스트레이터가 한 번 실행 +- **STATE.md 잠금**: 파일 수준 잠금 파일로 에이전트 간 동시 쓰기 손상 방지 + +--- + +### 6. Work Verification + +**명령어:** `/gsd-verify-work [N]` + +**목적:** 사용자 인수 테스트 — 각 결과물을 테스트하는 과정을 사용자와 함께 진행하고 실패를 자동으로 진단합니다. + +**요구사항.** +- REQ-VERIFY-01: 페이즈에서 테스트 가능한 결과물을 추출해야 합니다. +- REQ-VERIFY-02: 결과물을 하나씩 사용자 확인을 위해 제시해야 합니다. +- REQ-VERIFY-03: 실패를 자동으로 진단하는 디버그 에이전트를 생성해야 합니다. +- REQ-VERIFY-04: 식별된 문제에 대한 수정 계획을 작성해야 합니다. +- REQ-VERIFY-05: 서버/데이터베이스/시드/시작 파일을 수정하는 페이즈에 콜드 스타트 스모크 테스트를 삽입해야 합니다. +- REQ-VERIFY-06: 합격/불합격 결과가 담긴 UAT.md를 생성해야 합니다. + +**생성 산출물.** `{phase}-UAT.md` — 사용자 인수 테스트 결과, 문제 발견 시 수정 계획 포함 + +--- + +### 6.5. Ship + +**명령어:** `/gsd-ship [N] [--draft]` + +**목적:** 로컬 완료에서 병합된 PR로의 전환. 검증 통과 후 브랜치를 푸시하고, 계획 산출물에서 자동 생성된 본문으로 PR을 작성하며, 선택적으로 검토를 요청하고 STATE.md에 추적합니다. + +**요구사항.** +- REQ-SHIP-01: 배포 전 페이즈가 검증을 통과했는지 확인해야 합니다. +- REQ-SHIP-02: `gh` CLI를 통해 브랜치를 푸시하고 PR을 작성해야 합니다. +- REQ-SHIP-03: SUMMARY.md, VERIFICATION.md, REQUIREMENTS.md에서 PR 본문을 자동 생성해야 합니다. +- REQ-SHIP-04: 배포 상태와 PR 번호로 STATE.md를 업데이트해야 합니다. +- REQ-SHIP-05: 초안 PR을 위한 `--draft` 플래그를 지원해야 합니다. + +**전제 조건.** 페이즈 검증 완료, `gh` CLI 설치 및 인증, 피처 브랜치에서 작업 + +**생성 산출물.** 풍부한 본문이 있는 GitHub PR, STATE.md 업데이트 + +--- + +### 7. UI Review + +**명령어:** `/gsd-ui-review [N]` + +**목적:** 구현된 프론트엔드 코드의 소급 6기둥 시각적 감사. 모든 프로젝트에서 독립적으로 작동합니다. + +**요구사항.** +- REQ-UIREVIEW-01: 6개 기둥 각각을 1-4 척도로 점수 매겨야 합니다. +- REQ-UIREVIEW-02: Playwright CLI를 통해 `.planning/ui-reviews/`에 스크린샷을 캡처해야 합니다. +- REQ-UIREVIEW-03: 스크린샷 디렉토리에 `.gitignore`를 작성해야 합니다. +- REQ-UIREVIEW-04: 우선순위 수정사항 상위 3개를 식별해야 합니다. +- REQ-UIREVIEW-05: UI-SPEC.md 없이도 추상적인 품질 기준을 사용하여 독립적으로 작동해야 합니다. + +**6가지 감사 기둥(1-4 점수).** +1. **Copywriting** — CTA 레이블, 빈 상태, 오류 상태 +2. **Visuals** — 초점, 시각적 계층구조, 아이콘 접근성 +3. **Color** — 강조색 사용 규율, 60/30/10 준수 +4. **Typography** — 글꼴 크기/굵기 제약 준수 +5. **Spacing** — 그리드 정렬, 토큰 일관성 +6. **Experience Design** — 로딩/오류/빈 상태 커버리지 + +**생성 산출물.** `{padded_phase}-UI-REVIEW.md` — 점수와 우선순위 수정사항 + +--- + +### 8. Milestone Management + +**명령어:** `/gsd-audit-milestone`, `/gsd-complete-milestone`, `/gsd-new-milestone [name]` + +**목적:** 마일스톤 완료를 검증하고, 보관하고, 릴리스 태그를 지정하며, 다음 개발 주기를 시작합니다. + +**요구사항.** +- REQ-MILE-01: 감사는 모든 마일스톤 요구사항이 충족되었는지 확인해야 합니다. +- REQ-MILE-02: 감사는 스텁, 플레이스홀더 구현, 테스트되지 않은 코드를 감지해야 합니다. +- REQ-MILE-03: 감사는 페이즈 전반에 걸친 Nyquist 유효성 검사 준수 여부를 확인해야 합니다. +- REQ-MILE-04: 완료는 마일스톤 데이터를 MILESTONES.md에 보관해야 합니다. +- REQ-MILE-05: 완료는 릴리스용 git 태그 생성을 제안해야 합니다. +- REQ-MILE-06: 완료는 브랜칭 전략에 따라 스쿼시 병합 또는 히스토리 포함 병합을 제안해야 합니다. +- REQ-MILE-07: 완료는 UI 리뷰 스크린샷을 정리해야 합니다. +- REQ-MILE-08: 새 마일스톤은 new-project와 동일한 흐름을 따라야 합니다(질문 → 연구 → 요구사항 → 로드맵). +- REQ-MILE-09: 새 마일스톤은 기존 워크플로우 구성을 초기화해서는 안 됩니다. + +**갭 해소.** `/gsd-plan-milestone-gaps`는 감사에서 식별된 갭을 해소하는 페이즈를 생성합니다. + +--- + +## 계획 기능 + +### 9. Phase Management + +**명령어:** `/gsd-add-phase`, `/gsd-insert-phase [N]`, `/gsd-remove-phase [N]` + +**목적:** 개발 중 동적 로드맵 수정. + +**요구사항.** +- REQ-PHASE-01: 추가는 현재 로드맵의 끝에 새 페이즈를 추가해야 합니다. +- REQ-PHASE-02: 삽입은 기존 페이즈 사이에 소수 번호를 사용해야 합니다(예: 3.1). +- REQ-PHASE-03: 제거는 이후의 모든 페이즈 번호를 다시 매겨야 합니다. +- REQ-PHASE-04: 이미 실행된 페이즈 제거를 방지해야 합니다. +- REQ-PHASE-05: 모든 작업은 ROADMAP.md를 업데이트하고 페이즈 디렉토리를 생성/제거해야 합니다. + +--- + +### 10. Quick Mode + +**명령어:** `/gsd-quick [--full] [--discuss] [--research]` + +**목적:** GSD 보증을 제공하지만 더 빠른 경로로 임시 작업을 실행합니다. + +**요구사항.** +- REQ-QUICK-01: 자유형 작업 설명을 받아야 합니다. +- REQ-QUICK-02: 전체 워크플로우와 동일한 플래너 및 실행자 에이전트를 사용해야 합니다. +- REQ-QUICK-03: 기본적으로 연구, 계획 검사기, 검증자를 건너뛰어야 합니다. +- REQ-QUICK-04: `--full` 플래그는 계획 검사(최대 2회 반복)와 실행 후 검증을 활성화해야 합니다. +- REQ-QUICK-05: `--discuss` 플래그는 간단한 사전 계획 논의를 실행해야 합니다. +- REQ-QUICK-06: `--research` 플래그는 계획 전에 집중된 연구 에이전트를 생성해야 합니다. +- REQ-QUICK-07: 플래그는 조합 가능해야 합니다(`--discuss --research --full`). +- REQ-QUICK-08: 빠른 작업을 `.planning/quick/YYMMDD-xxx-slug/`에 추적해야 합니다. +- REQ-QUICK-09: 빠른 작업 실행에 대한 원자적 커밋을 생성해야 합니다. + +--- + +### 11. Autonomous Mode + +**명령어:** `/gsd-autonomous [--from N]` + +**목적:** 나머지 모든 페이즈를 자율적으로 실행합니다 — 페이즈별로 논의 → 계획 → 실행. + +**요구사항.** +- REQ-AUTO-01: 로드맵 순서대로 완료되지 않은 모든 페이즈를 반복해야 합니다. +- REQ-AUTO-02: 각 페이즈에 대해 논의 → 계획 → 실행을 실행해야 합니다. +- REQ-AUTO-03: 명시적 사용자 결정이 필요한 경우 일시 중지해야 합니다(회색 지대 수락, 블로커, 유효성 검사). +- REQ-AUTO-04: 동적으로 삽입된 페이즈를 감지하기 위해 각 페이즈 후 ROADMAP.md를 다시 읽어야 합니다. +- REQ-AUTO-05: `--from N` 플래그는 특정 페이즈 번호부터 시작해야 합니다. + +--- + +### 12. Freeform Routing + +**명령어:** `/gsd-do` + +**목적:** 자유형 텍스트를 분석하고 적절한 GSD 명령어로 라우팅합니다. + +**요구사항.** +- REQ-DO-01: 자연어 입력에서 사용자 의도를 파악해야 합니다. +- REQ-DO-02: 의도를 가장 적합한 GSD 명령어에 매핑해야 합니다. +- REQ-DO-03: 실행 전에 라우팅을 사용자에게 확인해야 합니다. +- REQ-DO-04: 프로젝트가 존재하는 경우와 없는 경우를 다르게 처리해야 합니다. + +--- + +### 13. Note Capture + +**명령어:** `/gsd-note` + +**목적:** 워크플로우를 방해하지 않고 아이디어를 즉시 캡처합니다. 타임스탬프가 있는 노트를 추가하거나, 모든 노트를 나열하거나, 노트를 구조화된 할 일로 승격합니다. + +**요구사항.** +- REQ-NOTE-01: 단일 write 호출로 타임스탬프가 있는 노트 파일을 저장해야 합니다. +- REQ-NOTE-02: 프로젝트 및 전역 범위의 모든 노트를 표시하는 `list` 하위 명령어를 지원해야 합니다. +- REQ-NOTE-03: 노트를 구조화된 할 일로 변환하는 `promote N` 하위 명령어를 지원해야 합니다. +- REQ-NOTE-04: 전역 범위 작업을 위한 `--global` 플래그를 지원해야 합니다. +- REQ-NOTE-05: task, question, bash를 사용해서는 안 됩니다 — 인라인으로만 실행됩니다. + +--- + +### 14. Auto-Advance (Next) + +**명령어:** `/gsd-next` + +**목적:** 현재 프로젝트 상태를 자동으로 감지하고 다음 논리적 워크플로우 단계로 진행합니다. 현재 어느 페이즈/단계에 있는지 기억할 필요가 없습니다. + +**요구사항.** +- REQ-NEXT-01: STATE.md, ROADMAP.md, 페이즈 디렉토리를 읽어 현재 위치를 확인해야 합니다. +- REQ-NEXT-02: 논의, 계획, 실행, 검증 중 어느 것이 필요한지 감지해야 합니다. +- REQ-NEXT-03: 올바른 명령어를 자동으로 호출해야 합니다. +- REQ-NEXT-04: 프로젝트가 없으면 `/gsd-new-project`를 제안해야 합니다. +- REQ-NEXT-05: 모든 페이즈가 완료되면 `/gsd-complete-milestone`을 제안해야 합니다. + +**상태 감지 로직.** +| 상태 | 액션 | +|-------|--------| +| `.planning/` 디렉토리 없음 | `/gsd-new-project` 제안 | +| 페이즈에 CONTEXT.md 없음 | `/gsd-discuss-phase` 실행 | +| 페이즈에 PLAN.md 파일 없음 | `/gsd-plan-phase` 실행 | +| 계획 있지만 SUMMARY.md 없음 | `/gsd-execute-phase` 실행 | +| 실행되었지만 VERIFICATION.md 없음 | `/gsd-verify-work` 실행 | +| 모든 페이즈 완료 | `/gsd-complete-milestone` 제안 | + +--- + +## 품질 보증 기능 + +### 15. Nyquist Validation + +**목적:** 코드 작성 전에 자동화된 테스트 커버리지를 페이즈 요구사항에 매핑합니다. Nyquist 샘플링 정리의 이름을 따서 명명되었으며 — 모든 요구사항에 피드백 신호가 존재하도록 보장합니다. + +**요구사항.** +- REQ-NYQ-01: plan-phase 연구 중에 기존 테스트 인프라를 감지해야 합니다. +- REQ-NYQ-02: 각 요구사항을 특정 테스트 명령어에 매핑해야 합니다. +- REQ-NYQ-03: 웨이브 0 작업(구현 전에 필요한 테스트 스캐폴딩)을 식별해야 합니다. +- REQ-NYQ-04: 계획 검사기는 Nyquist 준수를 8번째 검증 차원으로 적용해야 합니다. +- REQ-NYQ-05: `/gsd-validate-phase`를 통한 소급 유효성 검사를 지원해야 합니다. +- REQ-NYQ-06: `workflow.nyquist_validation: false`로 비활성화 가능해야 합니다. + +**생성 산출물.** `{phase}-VALIDATION.md` — 테스트 커버리지 계약 + +**소급 유효성 검사(`/gsd-validate-phase [N]`).** +- 구현을 스캔하고 요구사항을 테스트에 매핑합니다. +- 요구사항에 자동화된 검증이 없는 갭을 식별합니다. +- 테스트 생성을 위한 감사자를 생성합니다(최대 3회 시도). +- 구현 코드는 절대 수정하지 않습니다 — 테스트 파일과 VALIDATION.md만 수정합니다. +- 구현 버그는 사용자가 처리해야 할 에스컬레이션으로 표시합니다. + +--- + +### 16. Plan Checking + +**목적:** 실행 전에 계획이 페이즈 목표를 달성할 것인지를 목표 역방향으로 검증합니다. + +**요구사항.** +- REQ-PLANCK-01: 8가지 품질 차원에 대해 계획을 검증해야 합니다. +- REQ-PLANCK-02: 계획이 통과할 때까지 최대 3회 반복해야 합니다. +- REQ-PLANCK-03: 실패에 대한 구체적이고 실행 가능한 피드백을 생성해야 합니다. +- REQ-PLANCK-04: `workflow.plan_check: false`로 비활성화 가능해야 합니다. + +--- + +### 17. Post-Execution Verification + +**목적:** 코드베이스가 페이즈가 약속한 것을 제공하는지 자동으로 확인합니다. + +**요구사항.** +- REQ-POSTVER-01: 작업 완료가 아닌 페이즈 목표에 대해 확인해야 합니다. +- REQ-POSTVER-02: 합격/불합격 분석이 담긴 VERIFICATION.md를 생성해야 합니다. +- REQ-POSTVER-03: `/gsd-verify-work`가 처리할 문제를 기록해야 합니다. +- REQ-POSTVER-04: `workflow.verifier: false`로 비활성화 가능해야 합니다. + +--- + +### 18. Node Repair + +**목적:** 실행 중 작업 검증 실패 시 자율적 복구. + +**요구사항.** +- REQ-REPAIR-01: 실패를 분석하고 RETRY, DECOMPOSE, PRUNE 중 하나의 전략을 선택해야 합니다. +- REQ-REPAIR-02: RETRY는 구체적인 조정으로 재시도해야 합니다. +- REQ-REPAIR-03: DECOMPOSE는 작업을 더 작고 검증 가능한 하위 단계로 분해해야 합니다. +- REQ-REPAIR-04: PRUNE은 달성 불가능한 작업을 제거하고 사용자에게 에스컬레이션해야 합니다. +- REQ-REPAIR-05: 복구 예산을 준수해야 합니다(기본값: 작업당 2회 시도). +- REQ-REPAIR-06: `workflow.node_repair_budget`과 `workflow.node_repair`로 구성 가능해야 합니다. + +--- + +### 19. Health Validation + +**명령어:** `/gsd-health [--repair]` + +**목적:** `.planning/` 디렉토리 무결성을 검증하고 문제를 자동으로 복구합니다. + +**요구사항.** +- REQ-HEALTH-01: 누락된 필수 파일을 확인해야 합니다. +- REQ-HEALTH-02: 구성 일관성을 검증해야 합니다. +- REQ-HEALTH-03: 요약 없이 고아가 된 계획을 감지해야 합니다. +- REQ-HEALTH-04: 페이즈 번호 매기기와 로드맵 동기화를 확인해야 합니다. +- REQ-HEALTH-05: `--repair` 플래그는 복구 가능한 문제를 자동으로 수정해야 합니다. + +--- + +### 20. Cross-Phase Regression Gate + +**목적:** 페이즈 실행 후 이전 페이즈의 테스트 스위트를 실행하여 회귀가 여러 페이즈에 걸쳐 누적되는 것을 방지합니다. + +**요구사항.** +- REQ-REGR-01: 페이즈 실행 후 완료된 모든 이전 페이즈의 테스트 스위트를 실행해야 합니다. +- REQ-REGR-02: 모든 테스트 실패를 교차 페이즈 회귀로 보고해야 합니다. +- REQ-REGR-03: 회귀는 실행 후 검증 전에 표시되어야 합니다. +- REQ-REGR-04: 어느 이전 페이즈의 테스트가 실패했는지 식별해야 합니다. + +**실행 시점.** `/gsd-execute-phase` 중 검증자 단계 전에 자동으로 실행됩니다. + +--- + +### 21. Requirements Coverage Gate + +**목적:** 계획 완료 전에 모든 페이즈 요구사항이 최소 하나의 계획에 포함되어 있는지 확인합니다. + +**요구사항.** +- REQ-COVGATE-01: ROADMAP.md에서 페이즈에 할당된 모든 요구사항 ID를 추출해야 합니다. +- REQ-COVGATE-02: 각 요구사항이 최소 하나의 PLAN.md에 나타나는지 확인해야 합니다. +- REQ-COVGATE-03: 포함되지 않은 요구사항은 계획 완료를 차단해야 합니다. +- REQ-COVGATE-04: 계획 커버리지가 없는 특정 요구사항을 보고해야 합니다. + +**실행 시점.** `/gsd-plan-phase`의 계획 검사기 루프 후 자동으로 실행됩니다. + +--- + +## 컨텍스트 엔지니어링 기능 + +### 22. Context Window Monitoring + +**목적:** 컨텍스트가 부족할 때 사용자와 에이전트 모두에게 경고하여 컨텍스트 로트를 방지합니다. + +**요구사항.** +- REQ-CTX-01: 상태표시줄은 사용자에게 컨텍스트 사용률을 표시해야 합니다. +- REQ-CTX-02: 컨텍스트 모니터는 남은 용량 ≤35%(WARNING)에서 에이전트 대상 경고를 주입해야 합니다. +- REQ-CTX-03: 컨텍스트 모니터는 남은 용량 ≤25%(CRITICAL)에서 에이전트 대상 경고를 주입해야 합니다. +- REQ-CTX-04: 경고는 디바운스되어야 합니다(반복 경고 사이에 5회 도구 사용). +- REQ-CTX-05: 심각도 에스컬레이션(WARNING→CRITICAL)은 디바운스를 우회해야 합니다. +- REQ-CTX-06: 컨텍스트 모니터는 GSD 활성 프로젝트와 비활성 프로젝트를 구분해야 합니다. +- REQ-CTX-07: 경고는 권고 사항이어야 하며 사용자 선호도를 재정의하는 명령적 지시가 되어서는 안 됩니다. +- REQ-CTX-08: 모든 훅은 자동으로 실패해야 하며 도구 실행을 차단해서는 안 됩니다. + +**아키텍처.** 두 부분으로 구성된 브리지 시스템. +1. 상태표시줄이 `/tmp/OpenCode-ctx-{session}.json`에 지표를 기록합니다. +2. 컨텍스트 모니터가 지표를 읽고 `additionalContext` 경고를 주입합니다. + +--- + +### 23. Session Management + +**명령어:** `/gsd-pause-work`, `/gsd-resume-work`, `/gsd-progress` + +**목적:** 컨텍스트 초기화와 세션 간에 프로젝트 연속성을 유지합니다. + +**요구사항.** +- REQ-SESSION-01: 일시 중지는 현재 위치와 다음 단계를 `continue-here.md`와 구조화된 `HANDOFF.json`에 저장해야 합니다. +- REQ-SESSION-02: 재개는 HANDOFF.json(우선)이나 상태 파일(대체)에서 전체 프로젝트 컨텍스트를 복원해야 합니다. +- REQ-SESSION-03: 진행 상황은 현재 위치, 다음 액션, 전체 완료도를 표시해야 합니다. +- REQ-SESSION-04: 진행 상황은 모든 상태 파일(STATE.md, ROADMAP.md, 페이즈 디렉토리)을 읽어야 합니다. +- REQ-SESSION-05: 모든 세션 작업은 `/new`(컨텍스트 초기화) 후에도 작동해야 합니다. +- REQ-SESSION-06: HANDOFF.json은 블로커, 보류 중인 사람 액션, 진행 중인 작업 상태를 포함해야 합니다. +- REQ-SESSION-07: 재개는 세션 시작 시 즉시 사람 액션과 블로커를 표시해야 합니다. + +--- + +### 24. Session Reporting + +**명령어:** `/gsd-session-report` + +**목적:** 수행된 작업, 달성된 결과, 예상 리소스 사용량을 캡처하는 구조화된 세션 후 요약 문서를 생성합니다. + +**요구사항.** +- REQ-REPORT-01: STATE.md, git log, 계획/요약 파일에서 데이터를 수집해야 합니다. +- REQ-REPORT-02: 커밋 수, 실행된 계획, 진행된 페이즈를 포함해야 합니다. +- REQ-REPORT-03: 세션 활동을 기반으로 토큰 사용량과 비용을 추정해야 합니다. +- REQ-REPORT-04: 활성 블로커와 결정사항을 포함해야 합니다. +- REQ-REPORT-05: 다음 단계를 권장해야 합니다. + +**생성 산출물.** `.planning/reports/SESSION_REPORT.md` + +**보고서 섹션.** +- 세션 개요(기간, 마일스톤, 페이즈) +- 수행된 작업(커밋, 계획, 페이즈) +- 결과 및 결과물 +- 블로커 및 결정사항 +- 리소스 추정(토큰, 비용) +- 다음 단계 권장사항 + +--- + +### 25. Multi-Agent Orchestration + +**목적:** 각 작업에 대해 새로운 컨텍스트 창을 가진 전문 에이전트를 조율합니다. + +**요구사항.** +- REQ-ORCH-01: 각 에이전트는 새로운 컨텍스트 창을 받아야 합니다. +- REQ-ORCH-02: 오케스트레이터는 간결해야 합니다 — 에이전트를 생성하고 결과를 수집하여 다음으로 라우팅합니다. +- REQ-ORCH-03: 컨텍스트 페이로드는 모든 관련 프로젝트 산출물을 포함해야 합니다. +- REQ-ORCH-04: 병렬 에이전트는 진정으로 독립적이어야 합니다(공유 가변 상태 없음). +- REQ-ORCH-05: 에이전트 결과는 오케스트레이터가 처리하기 전에 디스크에 기록되어야 합니다. +- REQ-ORCH-06: 실패한 에이전트는 감지되어야 합니다(실제 출력과 보고된 실패를 대조 확인). + +--- + +### 26. Model Profiles + +**명령어:** `/gsd-set-profile ` + +**목적:** 각 에이전트가 사용하는 AI 모델을 제어하여 품질과 비용의 균형을 맞춥니다. + +**요구사항.** +- REQ-MODEL-01: 4가지 프로파일을 지원해야 합니다. `quality`, `balanced`, `budget`, `inherit` +- REQ-MODEL-02: 각 프로파일은 에이전트별 모델 티어를 정의해야 합니다(프로파일 표 참조). +- REQ-MODEL-03: 에이전트별 재정의는 프로파일보다 우선해야 합니다. +- REQ-MODEL-04: `inherit` 프로파일은 런타임의 현재 모델 선택을 따라야 합니다. +- REQ-MODEL-04a: `inherit` 프로파일은 비Anthropic 공급자(OpenRouter, 로컬 모델) 사용 시 예상치 못한 API 비용을 피하기 위해 사용해야 합니다. +- REQ-MODEL-05: 프로파일 전환은 프로그래밍 방식이어야 합니다(LLM 기반이 아닌 스크립트). +- REQ-MODEL-06: 모델 해석은 생성당 한 번이 아닌 오케스트레이션당 한 번 수행해야 합니다. + +**프로파일 할당.** + +| 에이전트 | `quality` | `balanced` | `budget` | `inherit` | +|-------|-----------|------------|----------|-----------| +| gsd-planner | Opus | Opus | Sonnet | Inherit | +| gsd-roadmapper | Opus | Sonnet | Sonnet | Inherit | +| gsd-executor | Opus | Sonnet | Sonnet | Inherit | +| gsd-phase-researcher | Opus | Sonnet | Haiku | Inherit | +| gsd-project-researcher | Opus | Sonnet | Haiku | Inherit | +| gsd-research-synthesizer | Sonnet | Sonnet | Haiku | Inherit | +| gsd-debugger | Opus | Sonnet | Sonnet | Inherit | +| gsd-codebase-mapper | Sonnet | Haiku | Haiku | Inherit | +| gsd-verifier | Sonnet | Sonnet | Haiku | Inherit | +| gsd-plan-checker | Sonnet | Sonnet | Haiku | Inherit | +| gsd-integration-checker | Sonnet | Sonnet | Haiku | Inherit | +| gsd-nyquist-auditor | Sonnet | Sonnet | Haiku | Inherit | + +--- + +## 브라운필드 기능 + +### 27. Codebase Mapping + +**명령어:** `/gsd-map-codebase [area]` + +**목적:** 새 프로젝트를 시작하기 전에 기존 코드베이스를 분석하여 GSD가 무엇이 존재하는지 이해하도록 합니다. + +**요구사항.** +- REQ-MAP-01: 각 분석 영역에 대한 병렬 매퍼 에이전트를 생성해야 합니다. +- REQ-MAP-02: `.planning/codebase/`에 구조화된 문서를 생성해야 합니다. +- REQ-MAP-03: 기술 스택, 아키텍처 패턴, 코딩 규범, 문제점을 감지해야 합니다. +- REQ-MAP-04: 이후 `/gsd-new-project`는 코드베이스 매핑을 로드하고 추가하는 내용에 대한 질문에 집중해야 합니다. +- REQ-MAP-05: 선택적 `[area]` 인수는 매핑 범위를 특정 영역으로 제한해야 합니다. + +**생성 산출물.** +| 문서 | 내용 | +|----------|---------| +| `STACK.md` | 언어, 프레임워크, 데이터베이스, 인프라 | +| `ARCHITECTURE.md` | 패턴, 레이어, 데이터 흐름, 경계 | +| `CONVENTIONS.md` | 명명, 파일 구성, 코드 스타일, 테스트 패턴 | +| `CONCERNS.md` | 기술 부채, 보안 문제, 성능 병목 | +| `STRUCTURE.md` | 디렉토리 레이아웃과 파일 구성 | +| `TESTING.md` | 테스트 인프라, 커버리지, 패턴 | +| `INTEGRATIONS.md` | 외부 서비스, API, 서드파티 의존성 | + +--- + +## 유틸리티 기능 + +### 28. Debug System + +**명령어:** `/gsd-debug [description]` + +**목적:** 컨텍스트 초기화 전반에 걸쳐 영구적인 상태로 체계적인 디버깅을 수행합니다. + +**요구사항.** +- REQ-DEBUG-01: `.planning/debug/`에 디버그 세션 파일을 작성해야 합니다. +- REQ-DEBUG-02: 가설, 증거, 제거된 이론을 추적해야 합니다. +- REQ-DEBUG-03: 디버깅이 컨텍스트 초기화 후에도 유지되도록 상태를 저장해야 합니다. +- REQ-DEBUG-04: 해결됨으로 표시하기 전에 사람의 확인을 요구해야 합니다. +- REQ-DEBUG-05: 해결된 세션은 `.planning/debug/knowledge-base.md`에 추가되어야 합니다. +- REQ-DEBUG-06: 재조사를 방지하기 위해 새 디버그 세션에서 지식 베이스를 참조해야 합니다. + +**디버그 세션 상태.** `gathering` → `investigating` → `fixing` → `verifying` → `awaiting_human_verify` → `resolved` + +--- + +### 29. Todo Management + +**명령어:** `/gsd-add-todo [desc]`, `/gsd-check-todos` + +**목적:** 세션 중 나중에 처리할 아이디어와 작업을 캡처합니다. + +**요구사항.** +- REQ-TODO-01: 현재 대화 컨텍스트에서 할 일을 캡처해야 합니다. +- REQ-TODO-02: 할 일은 `.planning/todos/pending/`에 저장되어야 합니다. +- REQ-TODO-03: 완료된 할 일은 `.planning/todos/done/`으로 이동해야 합니다. +- REQ-TODO-04: check-todos는 모든 보류 항목을 나열하고 하나를 선택하여 작업할 수 있어야 합니다. + +--- + +### 30. Statistics Dashboard + +**명령어:** `/gsd-stats` + +**목적:** 프로젝트 지표를 표시합니다 — 페이즈, 계획, 요구사항, git 히스토리, 타임라인. + +**요구사항.** +- REQ-STATS-01: 페이즈/계획 완료 수를 표시해야 합니다. +- REQ-STATS-02: 요구사항 커버리지를 표시해야 합니다. +- REQ-STATS-03: git 커밋 지표를 표시해야 합니다. +- REQ-STATS-04: 여러 출력 형식을 지원해야 합니다(json, table, bar). + +--- + +### 31. Update System + +**명령어:** `/gsd-update` + +**목적:** 변경 로그 미리보기와 함께 GSD를 최신 버전으로 업데이트합니다. + +**요구사항.** +- REQ-UPDATE-01: npm을 통해 새 버전을 확인해야 합니다. +- REQ-UPDATE-02: 업데이트 전에 새 버전의 변경 로그를 표시해야 합니다. +- REQ-UPDATE-03: 런타임을 인식하고 올바른 디렉토리를 대상으로 해야 합니다. +- REQ-UPDATE-04: 로컬에서 수정된 파일을 `gsd-local-patches/`에 백업해야 합니다. +- REQ-UPDATE-05: `/gsd-reapply-patches`는 업데이트 후 로컬 수정사항을 복원해야 합니다. + +--- + +### 32. Settings Management + +**명령어:** `/gsd-settings` + +**목적:** 워크플로우 토글과 모델 프로파일의 대화형 구성. + +**요구사항.** +- REQ-SETTINGS-01: 토글 옵션과 함께 현재 설정을 표시해야 합니다. +- REQ-SETTINGS-02: `.planning/config.json`을 업데이트해야 합니다. +- REQ-SETTINGS-03: 전역 기본값으로 저장하는 것을 지원해야 합니다(`~/.gsd/defaults.json`). + +**구성 가능한 설정.** +| 설정 | 유형 | 기본값 | 설명 | +|---------|------|---------|-------------| +| `mode` | enum | `interactive` | `interactive` 또는 `yolo`(자동 승인) | +| `granularity` | enum | `standard` | `coarse`, `standard`, 또는 `fine` | +| `model_profile` | enum | `balanced` | `quality`, `balanced`, `budget`, 또는 `inherit` | +| `workflow.research` | boolean | `true` | 계획 전 도메인 연구 | +| `workflow.plan_check` | boolean | `true` | 계획 검증 루프 | +| `workflow.verifier` | boolean | `true` | 실행 후 검증 | +| `workflow.auto_advance` | boolean | `false` | 논의→계획→실행 자동 연결 | +| `workflow.nyquist_validation` | boolean | `true` | Nyquist 테스트 커버리지 매핑 | +| `workflow.ui_phase` | boolean | `true` | UI 설계 계약 생성 | +| `workflow.ui_safety_gate` | boolean | `true` | 프론트엔드 페이즈에서 ui-phase 촉구 | +| `workflow.node_repair` | boolean | `true` | 자율적 작업 복구 | +| `workflow.node_repair_budget` | number | `2` | 작업당 최대 복구 시도 횟수 | +| `planning.commit_docs` | boolean | `true` | `.planning/` 파일을 git에 커밋 | +| `planning.search_gitignored` | boolean | `false` | 검색에 gitignore된 파일 포함 | +| `parallelization.enabled` | boolean | `true` | 독립적인 계획을 동시에 실행 | +| `git.branching_strategy` | enum | `none` | `none`, `phase`, 또는 `milestone` | + +--- + +### 33. Test Generation + +**명령어:** `/gsd-add-tests [N]` + +**목적:** UAT 기준과 구현을 기반으로 완료된 페이즈에 대한 테스트를 생성합니다. + +**요구사항.** +- REQ-TEST-01: 완료된 페이즈 구현을 분석해야 합니다. +- REQ-TEST-02: UAT 기준과 인수 기준을 기반으로 테스트를 생성해야 합니다. +- REQ-TEST-03: 기존 테스트 인프라 패턴을 사용해야 합니다. + +--- + +## 인프라 기능 + +### 34. Git Integration + +**목적:** 원자적 커밋, 브랜칭 전략, 깔끔한 히스토리 관리. + +**요구사항.** +- REQ-GIT-01: 각 작업은 고유한 원자적 커밋을 가져야 합니다. +- REQ-GIT-02: 커밋 메시지는 구조화된 형식을 따라야 합니다: `type(scope): description` +- REQ-GIT-03: 3가지 브랜칭 전략을 지원해야 합니다: `none`, `phase`, `milestone` +- REQ-GIT-04: phase 전략은 페이즈당 하나의 브랜치를 생성해야 합니다. +- REQ-GIT-05: milestone 전략은 마일스톤당 하나의 브랜치를 생성해야 합니다. +- REQ-GIT-06: complete-milestone은 스쿼시 병합(권장) 또는 히스토리 포함 병합을 제공해야 합니다. +- REQ-GIT-07: `.planning/` 파일에 대한 `commit_docs` 설정을 준수해야 합니다. +- REQ-GIT-08: `.gitignore`에서 `.planning/`을 자동 감지하고 커밋을 건너뛰어야 합니다. + +**커밋 형식.** +``` +type(phase-plan): description + +# 예시: +docs(08-02): complete user registration plan +feat(08-02): add email confirmation flow +fix(03-01): correct auth token expiry +``` + +--- + +### 35. CLI Tools + +**목적:** 반복적인 인라인 bash 패턴을 대체하는 워크플로우와 에이전트를 위한 프로그래밍 방식의 유틸리티. + +**요구사항.** +- REQ-CLI-01: 상태, 구성, 페이즈, 로드맵 작업을 위한 원자적 명령어를 제공해야 합니다. +- REQ-CLI-02: 각 워크플로우에 대한 모든 컨텍스트를 로드하는 복합 `init` 명령어를 제공해야 합니다. +- REQ-CLI-03: 기계 판독 가능한 출력을 위한 `--raw` 플래그를 지원해야 합니다. +- REQ-CLI-04: 샌드박스 하위 에이전트 작업을 위한 `--cwd` 플래그를 지원해야 합니다. +- REQ-CLI-05: 모든 작업은 Windows에서 슬래시 경로를 사용해야 합니다. + +**명령어 카테고리.** State(11개), Phase(5개), Roadmap(3개), Verify(8개), Template(2개), Frontmatter(4개), Scaffold(4개), Init(12개), Validate(2개), Progress, Stats, Todo + +--- + +### 36. Multi-Runtime Support + +**목적:** 6가지 다른 AI 코딩 에이전트 런타임에서 GSD를 실행합니다. + +**요구사항.** +- REQ-RUNTIME-01: OpenCode, OpenCode, Gemini CLI, Codex, Copilot, Antigravity를 지원해야 합니다. +- REQ-RUNTIME-02: 설치 프로그램은 런타임별로 콘텐츠를 변환해야 합니다(도구 이름, 경로, 프론트매터). +- REQ-RUNTIME-03: 설치 프로그램은 대화형 및 비대화형(`--OpenCode --global`) 모드를 모두 지원해야 합니다. +- REQ-RUNTIME-04: 설치 프로그램은 전역 및 로컬 설치를 모두 지원해야 합니다. +- REQ-RUNTIME-05: 제거는 다른 구성에 영향을 주지 않고 모든 GSD 파일을 깔끔하게 제거해야 합니다. +- REQ-RUNTIME-06: 설치 프로그램은 플랫폼 차이를 처리해야 합니다(Windows, macOS, Linux, WSL, Docker). + +**런타임 변환.** + +| 측면 | OpenCode | OpenCode | Gemini | Codex | Copilot | Antigravity | +|--------|------------|----------|--------|-------|---------|-------------| +| 명령어 | 슬래시 명령어 | 슬래시 명령어 | 슬래시 명령어 | Skills(TOML) | 슬래시 명령어 | Skills | +| 에이전트 형식 | OpenCode native | `mode: subagent` | OpenCode native | Skills | Tool mapping | Skills | +| 훅 이벤트 | `PostToolUse` | N/A | `AfterTool` | N/A | N/A | N/A | +| 구성 | `settings.json` | `opencode.json(c)` | `settings.json` | TOML | Instructions | Config | + +--- + +### 37. Hook System + +**목적:** 컨텍스트 모니터링, 상태 표시, 업데이트 확인을 위한 런타임 이벤트 훅. + +**요구사항.** +- REQ-HOOK-01: 상태표시줄은 모델, 현재 작업, 디렉토리, 컨텍스트 사용량을 표시해야 합니다. +- REQ-HOOK-02: 컨텍스트 모니터는 임계값에서 에이전트 대상 경고를 주입해야 합니다. +- REQ-HOOK-03: 업데이트 확인기는 세션 시작 시 백그라운드에서 실행되어야 합니다. +- REQ-HOOK-04: 모든 훅은 `CLAUDE_CONFIG_DIR` 환경 변수를 준수해야 합니다. +- REQ-HOOK-05: 모든 훅은 3초 stdin 타임아웃 가드를 포함해야 합니다. +- REQ-HOOK-06: 모든 훅은 오류 시 자동으로 실패해야 합니다. +- REQ-HOOK-07: 컨텍스트 사용량은 autocompact 버퍼(16.5% 예약)에 맞게 정규화해야 합니다. + +**상태표시줄 표시.** +``` +[⬆ /gsd-update │] model │ [current task │] directory [█████░░░░░ 50%] +``` + +색상 코드: <50% 초록, <65% 노랑, <80% 주황, ≥80% 해골 이모지와 함께 빨강 + +### 38. Developer Profiling + +**명령어:** `/gsd-profile-user [--questionnaire] [--refresh]` + +**목적:** OpenCode 세션 히스토리를 분석하여 8가지 차원에서 행동 프로파일을 구축하고, 개발자의 스타일에 맞게 OpenCode 응답을 개인화하는 산출물을 생성합니다. + +**차원.** +1. 커뮤니케이션 스타일(간결 vs 장황, 공식 vs 비공식) +2. 결정 패턴(신속 vs 신중, 위험 허용도) +3. 디버깅 접근 방식(체계적 vs 직관적, 로그 선호도) +4. UX 선호도(디자인 감각, 접근성 인식) +5. 벤더/기술 선택(프레임워크 선호도, 생태계 숙련도) +6. 불만 요인(워크플로우에서 마찰을 일으키는 요소) +7. 학습 스타일(문서 vs 예시, 깊이 선호도) +8. 설명 깊이(고수준 vs 구현 세부 사항) + +**생성 산출물.** +- `USER-PROFILE.md` — 증거 인용이 포함된 전체 행동 프로파일 +- `/gsd-dev-preferences` 명령어 — 모든 세션에서 선호도 로드 +- `AGENTS.md` 프로파일 섹션 — OpenCode가 자동으로 검색 + +**플래그.** +- `--questionnaire` — 세션 히스토리를 사용할 수 없을 때 대화형 설문지 대체 +- `--refresh` — 세션을 재분석하고 프로파일 재생성 + +**파이프라인 모듈.** +- `profile-pipeline.cjs` — 세션 스캐닝, 메시지 추출, 샘플링 +- `profile-output.cjs` — 프로파일 렌더링, 설문지, 산출물 생성 +- `gsd-user-profiler` 에이전트 — 세션 데이터에서 행동 분석 + +**요구사항.** +- REQ-PROF-01: 세션 분석은 최소 8가지 행동 차원을 다루어야 합니다. +- REQ-PROF-02: 프로파일은 실제 세션 메시지에서 증거를 인용해야 합니다. +- REQ-PROF-03: 세션 히스토리가 없을 때 설문지가 대체 수단으로 제공되어야 합니다. +- REQ-PROF-04: 생성된 산출물은 OpenCode가 검색할 수 있어야 합니다(AGENTS.md 통합). + +### 39. Execution Hardening + +**목적:** 교차 계획 실패가 연쇄적으로 발생하기 전에 잡아내는 실행 파이프라인에 대한 세 가지 추가 품질 개선. + +**구성 요소.** + +**1. 사전 웨이브 의존성 확인** (execute-phase) +웨이브 N+1을 생성하기 전에 이전 웨이브 산출물의 핵심 링크가 존재하고 올바르게 연결되어 있는지 확인합니다. 교차 계획 의존성 갭이 다운스트림 실패로 연쇄되기 전에 잡아냅니다. + +**2. 교차 계획 데이터 계약 — 차원 9** (plan-checker) +데이터 파이프라인을 공유하는 계획에 호환 가능한 변환이 있는지 확인하는 새 분석 차원입니다. 한 계획이 다른 계획이 원본 형태로 필요로 하는 데이터를 제거할 때 표시합니다. + +**3. 내보내기 수준 스팟 체크** (verify-phase) +레벨 3 배선 검증이 통과된 후 개별 내보내기의 실제 사용을 스팟 체크합니다. 배선된 파일에 존재하지만 호출되지 않는 데드 스토어를 잡아냅니다. + +**요구사항.** +- REQ-HARD-01: 사전 웨이브 확인은 다음 웨이브를 생성하기 전에 모든 이전 웨이브 산출물의 핵심 링크를 확인해야 합니다. +- REQ-HARD-02: 교차 계획 계약 확인은 계획 간 호환되지 않는 데이터 변환을 감지해야 합니다. +- REQ-HARD-03: 내보내기 스팟 체크는 배선된 파일의 데드 스토어를 식별해야 합니다. + +--- + +### 40. Verification Debt Tracking + +**명령어:** `/gsd-audit-uat` + +**목적:** 프로젝트가 미결 테스트가 있는 페이즈를 넘어 진행할 때 UAT/검증 항목이 자동으로 누락되는 것을 방지합니다. 모든 이전 페이즈에 걸쳐 검증 부채를 표시하여 항목이 잊히지 않도록 합니다. + +**구성 요소.** + +**1. 교차 페이즈 상태 확인** (progress.md 1.6단계) +모든 `/gsd-progress` 호출은 현재 마일스톤의 모든 페이즈에서 미결 항목(pending, skipped, blocked, human_needed)을 스캔합니다. 실행 가능한 링크가 포함된 비차단 경고 섹션을 표시합니다. + +**2. `status: partial`** (verify-work.md, UAT.md) +"세션 종료"와 "모든 테스트 해결" 사이를 구분하는 새 UAT 상태입니다. 테스트가 여전히 pending, blocked, 또는 이유 없이 skipped된 경우 `status: complete`를 방지합니다. + +**3. `blocked_by` 태그가 있는 `result: blocked`** (verify-work.md, UAT.md) +외부 의존성(서버, 물리적 장치, 릴리스 빌드, 서드파티 서비스)으로 인해 차단된 테스트의 새 테스트 결과 유형입니다. 건너뛴 테스트와는 별도로 분류됩니다. + +**4. HUMAN-UAT.md 영속성** (execute-phase.md) +검증이 `human_needed`를 반환할 때 항목은 `status: partial`이 있는 추적 가능한 HUMAN-UAT.md 파일로 저장됩니다. 교차 페이즈 상태 확인과 감사 시스템에 반영됩니다. + +**5. 페이즈 완료 경고** (phase.cjs, transition.md) +`phase complete` CLI는 JSON 출력에 검증 부채 경고를 반환합니다. 전환 워크플로우는 확인 전에 미결 항목을 표시합니다. + +**요구사항.** +- REQ-DEBT-01: `/gsd-progress`에서 모든 이전 페이즈의 미결 UAT/검증 항목을 표시해야 합니다. +- REQ-DEBT-02: 불완전한 테스트(partial)와 완료된 테스트(complete)를 구분해야 합니다. +- REQ-DEBT-03: 차단된 테스트를 `blocked_by` 태그로 분류해야 합니다. +- REQ-DEBT-04: human_needed 검증 항목을 추적 가능한 UAT 파일로 저장해야 합니다. +- REQ-DEBT-05: 검증 부채가 있을 때 페이즈 완료와 전환 중에 경고해야 합니다(비차단). +- REQ-DEBT-06: `/gsd-audit-uat`는 모든 페이즈를 스캔하고 테스트 가능성별로 항목을 분류하며 사람 테스트 계획을 생성해야 합니다. + +--- + +## v1.27 기능 + +### 41. Fast Mode + +**명령어:** `/gsd-fast [task description]` + +**목적:** 하위 에이전트를 생성하거나 PLAN.md 파일을 생성하지 않고 인라인으로 간단한 작업을 실행합니다. 계획 오버헤드를 정당화하기에는 너무 작은 작업에 사용합니다: 오타 수정, 구성 변경, 작은 리팩터링, 잊혀진 커밋, 간단한 추가. + +**요구사항.** +- REQ-FAST-01: 하위 에이전트 없이 현재 컨텍스트에서 직접 작업을 실행해야 합니다. +- REQ-FAST-02: 변경사항에 대한 원자적 git 커밋을 생성해야 합니다. +- REQ-FAST-03: 상태 일관성을 위해 `.planning/quick/`에 작업을 추적해야 합니다. +- REQ-FAST-04: 연구, 다단계 계획, 또는 검증이 필요한 작업에는 사용해서는 안 됩니다. + +**`/gsd-quick`과 비교하여 사용 시점.** +- `/gsd-fast` — 2분 이내에 실행 가능한 한 문장 작업(오타, 구성 변경, 작은 추가) +- `/gsd-quick` — 연구, 다단계 계획, 또는 검증이 필요한 모든 것 + +--- + +### 42. Cross-AI Peer Review + +**명령어:** `/gsd-review --phase N [--gemini] [--OpenCode] [--codex] [--all]` + +**목적:** 외부 AI CLI(Gemini, OpenCode, Codex)를 호출하여 페이즈 계획을 독립적으로 검토합니다. 검토자별 피드백이 담긴 구조화된 REVIEWS.md를 생성합니다. + +**요구사항.** +- REQ-REVIEW-01: 시스템에서 사용 가능한 AI CLI를 감지해야 합니다. +- REQ-REVIEW-02: 페이즈 계획에서 구조화된 검토 프롬프트를 작성해야 합니다. +- REQ-REVIEW-03: 선택된 각 CLI를 독립적으로 호출해야 합니다. +- REQ-REVIEW-04: 응답을 수집하고 `REVIEWS.md`를 생성해야 합니다. +- REQ-REVIEW-05: 검토는 `/gsd-plan-phase --reviews`가 사용할 수 있어야 합니다. + +**생성 산출물.** `{phase}-REVIEWS.md` — 검토자별 구조화된 피드백 + +--- + +### 43. Backlog Parking Lot + +**명령어:** `/gsd-add-backlog `, `/gsd-review-backlog`, `/gsd-plant-seed ` + +**목적:** 아직 적극적인 계획에 준비되지 않은 아이디어를 캡처합니다. 백로그 항목은 활성 페이즈 순서 밖에 있기 위해 999.x 번호를 사용합니다. 시드는 올바른 마일스톤에서 자동으로 표시되는 트리거 조건이 있는 미래 지향적 아이디어입니다. + +**요구사항.** +- REQ-BACKLOG-01: 백로그 항목은 활성 페이즈 순서 밖에 있기 위해 999.x 번호를 사용해야 합니다. +- REQ-BACKLOG-02: `/gsd-discuss-phase`와 `/gsd-plan-phase`가 작동할 수 있도록 페이즈 디렉토리를 즉시 생성해야 합니다. +- REQ-BACKLOG-03: `/gsd-review-backlog`는 항목별로 승격, 유지, 제거 액션을 지원해야 합니다. +- REQ-BACKLOG-04: 승격된 항목은 활성 마일스톤 순서로 번호가 다시 매겨져야 합니다. +- REQ-SEED-01: 시드는 표시 조건에 대한 전체 이유와 시기를 캡처해야 합니다. +- REQ-SEED-02: `/gsd-new-milestone`은 시드를 스캔하고 일치하는 항목을 표시해야 합니다. + +**생성 산출물.** +| 산출물 | 설명 | +|----------|-------------| +| `.planning/phases/999.x-slug/` | 백로그 항목 디렉토리 | +| `.planning/seeds/SEED-NNN-slug.md` | 트리거 조건이 있는 시드 | + +--- + +### 44. Persistent Context Threads + +**명령어:** `/gsd-thread [name | description]` + +**목적:** 여러 세션에 걸쳐 있지만 특정 페이즈에 속하지 않는 작업을 위한 가벼운 교차 세션 지식 저장소입니다. `/gsd-pause-work`보다 더 가볍습니다 — 페이즈 상태나 계획 컨텍스트가 없습니다. + +**요구사항.** +- REQ-THREAD-01: 생성, 나열, 재개 모드를 지원해야 합니다. +- REQ-THREAD-02: 스레드는 `.planning/threads/`에 마크다운 파일로 저장되어야 합니다. +- REQ-THREAD-03: 스레드 파일은 Goal, Context, References, Next Steps 섹션을 포함해야 합니다. +- REQ-THREAD-04: 스레드 재개는 전체 컨텍스트를 현재 세션에 로드해야 합니다. +- REQ-THREAD-05: 스레드는 페이즈나 백로그 항목으로 승격될 수 있어야 합니다. + +**생성 산출물.** `.planning/threads/{slug}.md` — 지속적 컨텍스트 스레드 + +--- + +### 45. PR Branch Filtering + +**명령어:** `/gsd-pr-branch [target branch]` + +**목적:** `.planning/` 커밋을 필터링하여 풀 리퀘스트에 적합한 깔끔한 브랜치를 생성합니다. 검토자는 GSD 계획 산출물이 아닌 코드 변경사항만 봅니다. + +**요구사항.** +- REQ-PRBRANCH-01: `.planning/` 파일만 수정하는 커밋을 식별해야 합니다. +- REQ-PRBRANCH-02: 계획 커밋이 필터링된 새 브랜치를 생성해야 합니다. +- REQ-PRBRANCH-03: 코드 변경사항은 커밋된 그대로 정확히 보존되어야 합니다. + +--- + +### 46. Security Hardening + +**목적:** GSD 계획 산출물에 대한 심층 방어 보안. GSD가 LLM 시스템 프롬프트가 되는 마크다운 파일을 생성하기 때문에, 이 파일로 흘러드는 사용자 제어 텍스트는 잠재적인 간접 프롬프트 주입 벡터입니다. + +**구성 요소.** + +**1. 중앙화된 보안 모듈** (`security.cjs`) +- 경로 순회 방지 — 파일 경로가 프로젝트 디렉토리 내에서 확인되는지 검증합니다. +- 프롬프트 주입 감지 — 사용자 제공 텍스트에서 알려진 주입 패턴을 스캔합니다. +- 안전한 JSON 파싱 — 상태 손상 전에 잘못된 입력을 포착합니다. +- 필드 이름 검증 — 구성 필드 이름을 통한 주입을 방지합니다. +- 셸 인수 검증 — 셸 보간 전에 사용자 텍스트를 살균합니다. + +**2. 프롬프트 주입 가드 훅** (`gsd-prompt-guard.js`) +`.planning/`을 대상으로 하는 write/edit 호출에서 주입 패턴을 스캔하는 PreToolUse 훅입니다. 정당한 작업을 차단하지 않고 인식을 위해 감지를 기록하는 권고 전용입니다. + +**3. 워크플로우 가드 훅** (`gsd-workflow-guard.js`) +OpenCode가 GSD 워크플로우 컨텍스트 밖에서 파일 편집을 시도하는 것을 감지하는 PreToolUse 훅입니다. 직접 편집 대신 `/gsd-quick` 또는 `/gsd-fast` 사용을 권고합니다. `hooks.workflow_guard`로 구성 가능합니다(기본값: false). + +**4. CI 준비 주입 스캐너** (`prompt-injection-scan.test.cjs`) +모든 에이전트, 워크플로우, 명령어 파일에서 포함된 주입 벡터를 스캔하는 테스트 스위트입니다. + +**요구사항.** +- REQ-SEC-01: 모든 사용자 제공 파일 경로는 프로젝트 디렉토리에 대해 검증되어야 합니다. +- REQ-SEC-02: 프롬프트 주입 패턴은 텍스트가 계획 산출물에 들어가기 전에 감지되어야 합니다. +- REQ-SEC-03: 보안 훅은 권고 전용이어야 합니다(정당한 작업을 절대 차단하지 않음). +- REQ-SEC-04: 사용자 입력의 JSON 파싱은 잘못된 데이터를 정상적으로 처리해야 합니다. +- REQ-SEC-05: macOS `/var` → `/private/var` 심링크 해석은 경로 검증에서 처리되어야 합니다. + +--- + +### 47. Multi-Repo Workspace Support + +**목적:** 모노저장소 및 멀티 저장소 설정에 대한 자동 감지 및 프로젝트 루트 해석. `.planning/`이 저장소 경계를 넘어 해석되어야 하는 워크스페이스를 지원합니다. + +**요구사항.** +- REQ-MULTIREPO-01: 멀티 저장소 워크스페이스 구성을 자동으로 감지해야 합니다. +- REQ-MULTIREPO-02: 저장소 경계를 넘어 프로젝트 루트를 해석해야 합니다. +- REQ-MULTIREPO-03: 실행자는 멀티 저장소 모드에서 저장소별 커밋 해시를 기록해야 합니다. + +--- + +### 48. Discussion Audit Trail + +**목적:** `/gsd-discuss-phase` 중에 `DISCUSSION-LOG.md`를 자동 생성하여 논의 중에 내려진 결정의 전체 감사 추적을 제공합니다. + +**요구사항.** +- REQ-DISCLOG-01: discuss-phase 중에 DISCUSSION-LOG.md를 자동 생성해야 합니다. +- REQ-DISCLOG-02: 로그는 질문, 제시된 옵션, 내려진 결정을 캡처해야 합니다. +- REQ-DISCLOG-03: 결정 ID는 discuss-phase에서 plan-phase까지 추적 가능해야 합니다. + +--- + +## v1.28 기능 + +### 49. Forensics + +**명령어:** `/gsd-forensics [description]` + +**목적:** 실패하거나 막힌 GSD 워크플로우의 사후 조사. + +**요구사항.** +- REQ-FORENSICS-01: git 히스토리에서 이상(막힌 루프, 긴 간격, 반복된 커밋)을 분석해야 합니다. +- REQ-FORENSICS-02: 산출물 무결성을 확인해야 합니다(완료된 페이즈에 예상 파일이 있는지). +- REQ-FORENSICS-03: `.planning/forensics/`에 저장된 마크다운 보고서를 생성해야 합니다. +- REQ-FORENSICS-04: 조사 결과로 GitHub 이슈 생성을 제안해야 합니다. +- REQ-FORENSICS-05: 프로젝트 파일을 수정해서는 안 됩니다(읽기 전용 조사). + +**생성 산출물.** +| 산출물 | 설명 | +|----------|-------------| +| `.planning/forensics/report-{timestamp}.md` | 사후 조사 보고서 | + +**프로세스.** +1. **스캔** — git 히스토리에서 이상 분석: 막힌 루프, 커밋 사이의 긴 간격, 반복된 동일 커밋 +2. **무결성 확인** — 완료된 페이즈에 예상 산출물 파일이 있는지 확인 +3. **보고** — `.planning/forensics/`에 저장된 조사 결과가 담긴 마크다운 보고서 생성 +4. **이슈** — 팀 가시성을 위해 조사 결과로 GitHub 이슈 생성 제안 + +--- + +### 50. Milestone Summary + +**명령어:** `/gsd-milestone-summary [version]` + +**목적:** 팀 온보딩을 위해 마일스톤 산출물에서 포괄적인 프로젝트 요약을 생성합니다. + +**요구사항.** +- REQ-SUMMARY-01: 페이즈 계획, 요약, 검증 결과를 집계해야 합니다. +- REQ-SUMMARY-02: 현재 및 보관된 마일스톤 모두에 대해 작동해야 합니다. +- REQ-SUMMARY-03: 탐색 가능한 단일 문서를 생성해야 합니다. + +**생성 산출물.** +| 산출물 | 설명 | +|----------|-------------| +| `MILESTONE-SUMMARY.md` | 마일스톤 산출물의 포괄적인 탐색 가능한 요약 | + +**프로세스.** +1. **수집** — 대상 마일스톤의 페이즈 계획, 요약, 검증 결과 집계 +2. **종합** — 교차 참조가 있는 단일 탐색 가능한 문서로 산출물 결합 +3. **출력** — 팀 온보딩과 이해관계자 검토에 적합한 `MILESTONE-SUMMARY.md` 작성 + +--- + +### 51. Workstream Namespacing + +**명령어:** `/gsd-workstreams` + +**목적:** 마일스톤의 다른 영역에서 동시 작업을 위한 병렬 워크스트림. + +**요구사항.** +- REQ-WS-01: 별도의 `.planning/workstreams/{name}/` 디렉토리에 워크스트림 상태를 격리해야 합니다. +- REQ-WS-02: 워크스트림 이름을 검증해야 합니다(영숫자 + 하이픈만, 경로 순회 없음). +- REQ-WS-03: list, create, switch, status, progress, complete, resume 하위 명령어를 지원해야 합니다. + +**생성 산출물.** +| 산출물 | 설명 | +|----------|-------------| +| `.planning/workstreams/{name}/` | 격리된 워크스트림 디렉토리 구조 | + +**프로세스.** +1. **생성** — 격리된 `.planning/workstreams/{name}/` 디렉토리로 명명된 워크스트림 초기화 +2. **전환** — 이후 GSD 명령어를 위한 활성 워크스트림 컨텍스트 변경 +3. **관리** — 워크스트림 나열, 상태 확인, 진행 상황 추적, 완료, 재개 + +--- + +### 52. Manager Dashboard + +**명령어:** `/gsd-manager` + +**목적:** 하나의 터미널에서 여러 페이즈를 관리하는 대화형 명령 센터. + +**요구사항.** +- REQ-MGR-01: 상태와 함께 모든 페이즈의 개요를 표시해야 합니다. +- REQ-MGR-02: 현재 마일스톤 범위로 필터링해야 합니다. +- REQ-MGR-03: 페이즈 의존성과 충돌을 표시해야 합니다. + +**생성 산출물.** 대화형 터미널 출력 + +**프로세스.** +1. **스캔** — 상태와 함께 현재 마일스톤의 모든 페이즈 로드 +2. **표시** — 페이즈 의존성, 충돌, 진행 상황을 보여주는 개요 렌더링 +3. **상호작용** — 개별 페이즈를 탐색, 검사, 또는 작업하는 명령어 수락 + +--- + +### 53. Assumptions Discussion Mode + +**명령어:** `/gsd-discuss-phase` with `workflow.discuss_mode: 'assumptions'` + +**목적:** 인터뷰 스타일 질문을 코드베이스 우선 가정 분석으로 대체합니다. + +**요구사항.** +- REQ-ASSUME-01: 질문하기 전에 코드베이스를 분석하여 구조화된 가정을 생성해야 합니다. +- REQ-ASSUME-02: 가정을 신뢰도 수준별로 분류해야 합니다(Confident/Likely/Unclear). +- REQ-ASSUME-03: 기본 논의 모드와 동일한 CONTEXT.md 형식을 생성해야 합니다. +- REQ-ASSUME-04: 신뢰도 기반 건너뛰기 게이트를 지원해야 합니다(모두 HIGH이면 질문 없음). + +**생성 산출물.** +| 산출물 | 설명 | +|----------|-------------| +| `{phase}-CONTEXT.md` | 기본 논의 모드와 동일한 형식 | + +**프로세스.** +1. **분석** — 구현 접근 방식에 대한 구조화된 가정을 생성하기 위해 코드베이스 스캔 +2. **분류** — 가정을 신뢰도 수준별로 분류: Confident, Likely, Unclear +3. **게이트** — 모든 가정이 HIGH 신뢰도라면 질문 완전히 건너뛰기 +4. **확인** — 불명확한 가정을 사용자에게 타겟팅된 질문으로 제시 +5. **출력** — 기본 논의 모드와 동일한 형식으로 `{phase}-CONTEXT.md` 생성 + +--- + +### 54. UI Phase Auto-Detection + +**일부:** `/gsd-new-project` 및 `/gsd-progress` + +**목적:** UI 중심 프로젝트를 자동으로 감지하고 `/gsd-ui-phase` 권장사항을 표시합니다. + +**요구사항.** +- REQ-UI-DETECT-01: 프로젝트 설명에서 UI 신호를 감지해야 합니다(키워드, 프레임워크 참조). +- REQ-UI-DETECT-02: 해당하는 경우 ROADMAP.md 페이즈에 `ui_hint`를 주석으로 추가해야 합니다. +- REQ-UI-DETECT-03: UI 중심 페이즈의 다음 단계에서 `/gsd-ui-phase`를 제안해야 합니다. +- REQ-UI-DETECT-04: `/gsd-ui-phase`를 필수로 만들어서는 안 됩니다. + +**프로세스.** +1. **감지** — UI 신호(키워드, 프레임워크 참조)에 대한 프로젝트 설명 및 기술 스택 스캔 +2. **주석** — ROADMAP.md의 해당 페이즈에 `ui_hint` 표시 추가 +3. **표시** — UI 중심 페이즈의 다음 단계에 `/gsd-ui-phase` 권장사항 포함 + +--- + +### 55. Multi-Runtime Installer Selection + +**일부:** `npx gsd-opencode` + +**목적:** 단일 대화형 설치 세션에서 여러 런타임을 선택합니다. + +**요구사항.** +- REQ-MULTI-RT-01: 대화형 프롬프트는 다중 선택을 지원해야 합니다(예: OpenCode + Gemini). +- REQ-MULTI-RT-02: CLI 플래그는 비대화형 설치에서 계속 작동해야 합니다. + +**프로세스.** +1. **감지** — 시스템에서 사용 가능한 AI CLI 런타임 식별 +2. **프롬프트** — 런타임 선택을 위한 다중 선택 인터페이스 표시 +3. **설치** — 단일 세션에서 선택된 모든 런타임에 GSD 구성 diff --git a/gsd-opencode/docs/ko-KR/README.md b/gsd-opencode/docs/ko-KR/README.md new file mode 100644 index 0000000..33a449c --- /dev/null +++ b/gsd-opencode/docs/ko-KR/README.md @@ -0,0 +1,29 @@ +# GSD 문서 + +Get Shit Done (GSD) 프레임워크의 종합 문서입니다. GSD는 AI 코딩 에이전트를 위한 메타 프롬프팅, 컨텍스트 엔지니어링, 스펙 기반 개발 시스템입니다. + +언어 버전: [English](README.md) · [Português (pt-BR)](pt-BR/README.md) · [日本語](ja-JP/README.md) · [简体中文](zh-CN/README.md) · [한국어](ko-KR/README.md) + +## 문서 목차 + +| 문서 | 대상 독자 | 설명 | +|------|-----------|------| +| [Architecture](ARCHITECTURE.md) | 기여자, 고급 사용자 | 시스템 아키텍처, 에이전트 모델, 데이터 흐름, 내부 설계 | +| [Feature Reference](FEATURES.md) | 전체 사용자 | 요구사항이 포함된 전체 기능 및 함수 문서 | +| [Command Reference](COMMANDS.md) | 전체 사용자 | 모든 명령어의 구문, 플래그, 옵션 및 예제 | +| [Configuration Reference](CONFIGURATION.md) | 전체 사용자 | 전체 설정 스키마, 워크플로우 토글, 모델 프로필, git 브랜칭 | +| [CLI Tools Reference](CLI-TOOLS.md) | 기여자, 에이전트 작성자 | 워크플로우 및 에이전트를 위한 `gsd-tools.cjs` 프로그래매틱 API | +| [Agent Reference](AGENTS.md) | 기여자, 고급 사용자 | 15개 전문 에이전트의 역할, 도구, 스폰 패턴 | +| [User Guide](USER-GUIDE.md) | 전체 사용자 | 워크플로우 안내, 문제 해결, 복구 방법 | +| [Context Monitor](context-monitor.md) | 전체 사용자 | 컨텍스트 윈도우 모니터링 훅 아키텍처 | +| [Discuss Mode](workflow-discuss-mode.md) | 전체 사용자 | discuss 단계의 assumptions 모드와 interview 모드 | + +## 빠른 링크 + +- **v1.28의 새로운 기능:** Forensics, milestone 요약, workstream, assumptions 모드, UI 자동 감지, manager 대시보드 +- **시작하기:** [README](../README.md) → 설치 → `/gsd-new-project` +- **전체 워크플로우 안내:** [User Guide](USER-GUIDE.md) +- **모든 명령어 한눈에 보기:** [Command Reference](COMMANDS.md) +- **GSD 설정하기:** [Configuration Reference](CONFIGURATION.md) +- **시스템 내부 동작 원리:** [Architecture](ARCHITECTURE.md) +- **기여 또는 확장:** [CLI Tools Reference](CLI-TOOLS.md) + [Agent Reference](AGENTS.md) diff --git a/gsd-opencode/docs/ko-KR/USER-GUIDE.md b/gsd-opencode/docs/ko-KR/USER-GUIDE.md new file mode 100644 index 0000000..710b43c --- /dev/null +++ b/gsd-opencode/docs/ko-KR/USER-GUIDE.md @@ -0,0 +1,842 @@ +# GSD 사용자 가이드 + +워크플로우, 문제 해결, 설정에 대한 상세 레퍼런스입니다. 빠른 시작 설정은 [README](../README.md)를 참고하세요. + +--- + +## 목차 + +- [워크플로우 다이어그램](#워크플로우-다이어그램) +- [UI 설계 계약](#ui-설계-계약) +- [백로그 및 스레드](#백로그-및-스레드) +- [워크스트림](#워크스트림) +- [보안](#보안) +- [명령어 레퍼런스](#명령어-레퍼런스) +- [설정 레퍼런스](#설정-레퍼런스) +- [사용 예시](#사용-예시) +- [문제 해결](#문제-해결) +- [복구 빠른 레퍼런스](#복구-빠른-레퍼런스) + +--- + +## 워크플로우 다이어그램 + +### 전체 프로젝트 생명주기 + +``` + ┌──────────────────────────────────────────────────┐ + │ NEW PROJECT │ + │ /gsd-new-project │ + │ Questions -> Research -> Requirements -> Roadmap│ + └─────────────────────────┬────────────────────────┘ + │ + ┌──────────────▼─────────────┐ + │ FOR EACH PHASE: │ + │ │ + │ ┌────────────────────┐ │ + │ │ /gsd-discuss-phase │ │ <- Lock in preferences + │ └──────────┬─────────┘ │ + │ │ │ + │ ┌──────────▼─────────┐ │ + │ │ /gsd-ui-phase │ │ <- Design contract (frontend) + │ └──────────┬─────────┘ │ + │ │ │ + │ ┌──────────▼─────────┐ │ + │ │ /gsd-plan-phase │ │ <- Research + Plan + Verify + │ └──────────┬─────────┘ │ + │ │ │ + │ ┌──────────▼─────────┐ │ + │ │ /gsd-execute-phase │ │ <- Parallel execution + │ └──────────┬─────────┘ │ + │ │ │ + │ ┌──────────▼─────────┐ │ + │ │ /gsd-verify-work │ │ <- Manual UAT + │ └──────────┬─────────┘ │ + │ │ │ + │ ┌──────────▼─────────┐ │ + │ │ /gsd-ship │ │ <- Create PR (optional) + │ └──────────┬─────────┘ │ + │ │ │ + │ Next Phase?────────────┘ + │ │ No + └─────────────┼──────────────┘ + │ + ┌───────────────▼──────────────┐ + │ /gsd-audit-milestone │ + │ /gsd-complete-milestone │ + └───────────────┬──────────────┘ + │ + Another milestone? + │ │ + Yes No -> Done! + │ + ┌───────▼──────────────┐ + │ /gsd-new-milestone │ + └──────────────────────┘ +``` + +### 계획 에이전트 조정 + +``` + /gsd-plan-phase N + │ + ├── Phase Researcher (x4 parallel) + │ ├── Stack researcher + │ ├── Features researcher + │ ├── Architecture researcher + │ └── Pitfalls researcher + │ │ + │ ┌──────▼──────┐ + │ │ RESEARCH.md │ + │ └──────┬──────┘ + │ │ + │ ┌──────▼──────┐ + │ │ Planner │ <- Reads PROJECT.md, REQUIREMENTS.md, + │ │ │ CONTEXT.md, RESEARCH.md + │ └──────┬──────┘ + │ │ + │ ┌──────▼───────────┐ ┌────────┐ + │ │ Plan Checker │────>│ PASS? │ + │ └──────────────────┘ └───┬────┘ + │ │ + │ Yes │ No + │ │ │ │ + │ │ └───┘ (loop, up to 3x) + │ │ + │ ┌─────▼──────┐ + │ │ PLAN files │ + │ └────────────┘ + └── Done +``` + +### 검증 아키텍처 (Nyquist 레이어) + +plan-phase 조사 단계에서 GSD는 코드 작성 전에 각 페이즈 요구사항에 대한 자동화된 테스트 커버리지를 매핑합니다. 이를 통해 OpenCode의 실행자가 작업을 커밋할 때 몇 초 안에 검증할 수 있는 피드백 메커니즘이 이미 갖춰져 있습니다. + +조사자는 기존 테스트 인프라를 감지하고 각 요구사항을 특정 테스트 명령어에 매핑하며 구현 시작 전에 생성해야 할 테스트 스캐폴딩을 식별합니다 (Wave 0 작업). + +계획 검사기는 이를 8번째 검증 차원으로 적용합니다. 작업에 자동화된 검증 명령어가 없는 계획은 승인되지 않습니다. + +**출력:** `{phase}-VALIDATION.md` — 해당 페이즈의 피드백 계약. + +**비활성화:** 테스트 인프라가 중요하지 않은 빠른 프로토타이핑 페이즈에서는 `/gsd-settings`에서 `workflow.nyquist_validation: false`로 설정하세요. + +### 소급 검증 (`/gsd-validate-phase`) + +Nyquist 검증 도입 전에 실행된 페이즈나 전통적인 테스트 스위트만 있는 기존 코드베이스의 경우 커버리지 갭을 소급하여 감사하고 보완할 수 있습니다. + +``` + /gsd-validate-phase N + | + +-- Detect state (VALIDATION.md exists? SUMMARY.md exists?) + | + +-- Discover: scan implementation, map requirements to tests + | + +-- Analyze gaps: which requirements lack automated verification? + | + +-- Present gap plan for approval + | + +-- Spawn auditor: generate tests, run, debug (max 3 attempts) + | + +-- Update VALIDATION.md + | + +-- COMPLIANT -> all requirements have automated checks + +-- PARTIAL -> some gaps escalated to manual-only +``` + +감사자는 구현 코드를 수정하지 않으며 테스트 파일과 VALIDATION.md만 수정합니다. 테스트에서 구현 버그가 발견되면 사용자가 처리할 수 있도록 에스컬레이션으로 표시됩니다. + +**사용 시점:** Nyquist가 활성화되기 전에 계획된 페이즈를 실행한 후 또는 `/gsd-audit-milestone`에서 Nyquist 준수 갭이 발견된 후에 사용합니다. + +### 가정 토론 모드 + +기본적으로 `/gsd-discuss-phase`는 구현 선호도에 대한 개방형 질문을 합니다. 가정 모드는 이를 역전시킵니다. GSD가 먼저 코드베이스를 읽고 페이즈를 어떻게 구축할지에 대한 구조화된 가정을 제시한 후 수정사항만 요청합니다. + +**활성화:** `/gsd-settings`에서 `workflow.discuss_mode`를 `'assumptions'`로 설정합니다. + +**작동 방식.** +1. PROJECT.md, 코드베이스 매핑, 기존 관례를 읽습니다. +2. 구조화된 가정 목록을 생성합니다 (기술 선택, 패턴, 파일 위치). +3. 가정을 확인, 수정 또는 확장하도록 제시합니다. +4. 확인된 가정으로 CONTEXT.md를 작성합니다. + +**사용 시점.** +- 코드베이스를 잘 아는 숙련된 개발자 +- 개방형 질문이 속도를 저해하는 빠른 반복 개발 +- 패턴이 잘 확립되고 예측 가능한 프로젝트 + +전체 discuss-mode 레퍼런스는 [docs/workflow-discuss-mode.md](workflow-discuss-mode.md)를 참고하세요. + +--- + +## UI 설계 계약 + +### 배경 + +AI 생성 프론트엔드가 시각적으로 일관성이 없는 이유는 OpenCode의 UI 능력이 부족해서가 아닙니다. 실행 전에 설계 계약이 존재하지 않았기 때문입니다. 공유 간격 척도, 색상 계약, 또는 카피라이팅 기준 없이 구축된 다섯 개의 컴포넌트는 다섯 가지 약간씩 다른 시각적 결정을 만들어냅니다. + +`/gsd-ui-phase`는 계획 전에 설계 계약을 확정합니다. `/gsd-ui-review`는 실행 후 결과를 감사합니다. + +### 명령어 + +| 명령어 | 설명 | +|--------|------| +| `/gsd-ui-phase [N]` | 프론트엔드 페이즈를 위한 UI-SPEC.md 설계 계약 생성 | +| `/gsd-ui-review [N]` | 구현된 UI의 6개 기둥 기반 시각적 감사 소급 수행 | + +### 워크플로우: `/gsd-ui-phase` + +**실행 시점:** `/gsd-discuss-phase` 이후, `/gsd-plan-phase` 이전 — 프론트엔드/UI 작업이 포함된 페이즈. + +**흐름.** +1. CONTEXT.md, RESEARCH.md, REQUIREMENTS.md에서 기존 결정사항을 읽습니다. +2. 디자인 시스템 상태를 감지합니다 (shadcn components.json, Tailwind 설정, 기존 토큰). +3. shadcn 초기화 게이트 — React/Next.js/Vite 프로젝트에 없으면 초기화를 제안합니다. +4. 아직 답변되지 않은 설계 계약 질문만 묻습니다 (간격, 타이포그래피, 색상, 카피라이팅, 레지스트리 안전). +5. 페이즈 디렉터리에 `{phase}-UI-SPEC.md`를 작성합니다. +6. 6개 차원에 대해 검증합니다 (카피라이팅, 시각, 색상, 타이포그래피, 간격, 레지스트리 안전). +7. BLOCKED인 경우 수정 루프 (최대 2회 반복). + +**출력:** `.planning/phases/{phase-dir}/`의 `{padded_phase}-UI-SPEC.md` + +### 워크플로우: `/gsd-ui-review` + +**실행 시점:** `/gsd-execute-phase` 또는 `/gsd-verify-work` 이후 — 프론트엔드 코드가 있는 모든 프로젝트. + +**독립 실행:** 모든 프로젝트에서 작동하며 GSD 관리 프로젝트가 아니어도 됩니다. UI-SPEC.md가 없으면 추상적인 6개 기둥 기준으로 감사합니다. + +**6개 기둥 (각 1-4점 평가).** +1. 카피라이팅 — CTA 레이블, 빈 상태, 오류 상태 +2. 시각 — 초점, 시각적 계층, 아이콘 접근성 +3. 색상 — 강조 사용 규율, 60/30/10 준수 +4. 타이포그래피 — 폰트 크기/굵기 제약 준수 +5. 간격 — 그리드 정렬, 토큰 일관성 +6. 경험 디자인 — 로딩/오류/빈 상태 커버리지 + +**출력:** 점수와 상위 3개 우선 수정사항이 포함된 페이즈 디렉터리의 `{padded_phase}-UI-REVIEW.md` + +### 설정 + +| 설정 | 기본값 | 설명 | +|------|--------|------| +| `workflow.ui_phase` | `true` | 프론트엔드 페이즈를 위한 UI 설계 계약 생성 | +| `workflow.ui_safety_gate` | `true` | plan-phase가 프론트엔드 페이즈에서 /gsd-ui-phase 실행을 유도합니다 | + +두 설정 모두 부재 시 활성화 패턴을 따릅니다. `/gsd-settings`에서 비활성화할 수 있습니다. + +### shadcn 초기화 + +React/Next.js/Vite 프로젝트에서 `components.json`이 없으면 UI 조사자가 shadcn 초기화를 제안합니다. 흐름은 다음과 같습니다. + +1. `ui.shadcn.com/create`를 방문하여 프리셋을 구성합니다. +2. 프리셋 문자열을 복사합니다. +3. `npx shadcn init --preset {paste}`를 실행합니다. +4. 프리셋은 전체 디자인 시스템(색상, 테두리 반경, 폰트)을 인코딩합니다. + +프리셋 문자열은 GSD의 1급 계획 아티팩트가 되어 페이즈와 마일스톤에 걸쳐 재현 가능합니다. + +### 레지스트리 안전 게이트 + +서드파티 shadcn 레지스트리는 임의의 코드를 주입할 수 있습니다. 안전 게이트는 다음을 요구합니다. +- `npx shadcn view {component}` — 설치 전 검사 +- `npx shadcn diff {component}` — 공식 버전과 비교 + +`workflow.ui_safety_gate` 설정 토글로 제어됩니다. + +### 스크린샷 저장 + +`/gsd-ui-review`는 Playwright CLI를 통해 `.planning/ui-reviews/`에 스크린샷을 캡처합니다. 바이너리 파일이 git에 포함되지 않도록 `.gitignore`가 자동으로 생성됩니다. 스크린샷은 `/gsd-complete-milestone` 실행 시 정리됩니다. + +--- + +## 백로그 및 스레드 + +### 백로그 파킹 롯 + +활성 계획에 아직 준비되지 않은 아이디어는 999.x 번호 체계를 사용하여 백로그에 보관하며 활성 페이즈 순서 밖에 유지됩니다. + +``` +/gsd-add-backlog "GraphQL API layer" # Creates 999.1-graphql-api-layer/ +/gsd-add-backlog "Mobile responsive" # Creates 999.2-mobile-responsive/ +``` + +백로그 항목은 전체 페이즈 디렉터리를 얻으므로 `/gsd-discuss-phase 999.1`로 아이디어를 더 탐구하거나 준비가 되면 `/gsd-plan-phase 999.1`을 사용할 수 있습니다. + +`/gsd-review-backlog`으로 **검토 및 승격**합니다 — 모든 백로그 항목을 표시하고 승격 (활성 순서로 이동), 유지 (백로그에 남김), 또는 제거 (삭제)를 선택할 수 있습니다. + +### 시드 + +시드는 트리거 조건이 있는 미래 지향적인 아이디어입니다. 백로그 항목과 달리 시드는 적절한 마일스톤 시점에 자동으로 표면화됩니다. + +``` +/gsd-plant-seed "Add real-time collab when WebSocket infra is in place" +``` + +시드는 전체 WHY와 언제 표면화할지를 보존합니다. `/gsd-new-milestone`은 모든 시드를 스캔하여 일치 항목을 제시합니다. + +**저장 위치:** `.planning/seeds/SEED-NNN-slug.md` + +### 지속적인 컨텍스트 스레드 + +스레드는 여러 세션에 걸쳐 이어지지만 특정 페이즈에 속하지 않는 작업을 위한 경량 교차 세션 지식 저장소입니다. + +``` +/gsd-thread # List all threads +/gsd-thread fix-deploy-key-auth # Resume existing thread +/gsd-thread "Investigate TCP timeout" # Create new thread +``` + +스레드는 `/gsd-pause-work`보다 가볍습니다. 페이즈 상태나 계획 컨텍스트가 없습니다. 각 스레드 파일에는 목표, 컨텍스트, 참조, 다음 단계 섹션이 포함됩니다. + +스레드가 성숙해지면 페이즈(`/gsd-add-phase`)나 백로그 항목(`/gsd-add-backlog`)으로 승격할 수 있습니다. + +**저장 위치:** `.planning/threads/{slug}.md` + +--- + +## 워크스트림 + +워크스트림을 사용하면 상태 충돌 없이 여러 마일스톤 영역을 동시에 작업할 수 있습니다. 각 워크스트림은 독립적인 `.planning/` 상태를 가지므로 워크스트림 간 전환 시 진행 상황이 덮어쓰이지 않습니다. + +**사용 시점:** 서로 다른 관심 영역(예: 백엔드 API와 프론트엔드 대시보드)에 걸친 마일스톤 기능을 독립적으로 계획, 실행 또는 토론하면서 컨텍스트 혼합 없이 작업하고 싶을 때 사용합니다. + +### 명령어 + +| 명령어 | 목적 | +|--------|------| +| `/gsd-workstreams create ` | 격리된 계획 상태로 새 워크스트림 생성 | +| `/gsd-workstreams switch ` | 활성 컨텍스트를 다른 워크스트림으로 전환 | +| `/gsd-workstreams list` | 모든 워크스트림과 활성 워크스트림 표시 | +| `/gsd-workstreams complete ` | 워크스트림을 완료로 표시하고 상태 아카이브 | + +### 작동 방식 + +각 워크스트림은 자체 `.planning/` 디렉터리 하위 트리를 유지합니다. 워크스트림을 전환하면 GSD가 활성 계획 컨텍스트를 교체하여 `/gsd-progress`, `/gsd-discuss-phase`, `/gsd-plan-phase` 및 기타 명령어가 해당 워크스트림의 상태로 동작합니다. + +이는 `/gsd-new-workspace`(별도 저장소 worktree를 생성)보다 가볍습니다. 워크스트림은 동일한 코드베이스와 git 히스토리를 공유하지만 계획 아티팩트를 격리합니다. + +--- + +## 보안 + +### 심층 방어 (v1.27) + +GSD는 LLM 시스템 프롬프트가 되는 마크다운 파일을 생성합니다. 즉 계획 아티팩트로 유입되는 사용자 제어 텍스트는 잠재적인 간접 프롬프트 인젝션 벡터입니다. v1.27에서 중앙화된 보안 강화가 도입되었습니다. + +**경로 순회 방지.** +모든 사용자 제공 파일 경로(`--text-file`, `--prd`)는 프로젝트 디렉터리 내에서 해석되는지 검증합니다. macOS `/var` → `/private/var` 심볼릭 링크 해석을 처리합니다. + +**프롬프트 인젝션 감지.** +`security.cjs` 모듈은 사용자 제공 텍스트가 계획 아티팩트에 입력되기 전에 알려진 인젝션 패턴(역할 재정의, 지시 우회, 시스템 태그 인젝션)을 스캔합니다. + +**런타임 훅.** +- `gsd-prompt-guard.js` — `.planning/`에 대한 write/edit 호출에서 인젝션 패턴 스캔 (항상 활성, 권고만) +- `gsd-workflow-guard.js` — GSD 워크플로우 컨텍스트 밖의 파일 편집 시 경고 (`hooks.workflow_guard`로 선택적 활성화) + +**CI 스캐너.** +`prompt-injection-scan.test.cjs`는 모든 에이전트, 워크플로우, 명령어 파일에서 내장된 인젝션 벡터를 스캔합니다. 테스트 스위트의 일부로 실행됩니다. + +--- + +### 실행 웨이브 조정 + +``` + /gsd-execute-phase N + │ + ├── Analyze plan dependencies + │ + ├── Wave 1 (independent plans): + │ ├── Executor A (fresh 200K context) -> commit + │ └── Executor B (fresh 200K context) -> commit + │ + ├── Wave 2 (depends on Wave 1): + │ └── Executor C (fresh 200K context) -> commit + │ + └── Verifier + └── Check codebase against phase goals + │ + ├── PASS -> VERIFICATION.md (success) + └── FAIL -> Issues logged for /gsd-verify-work +``` + +### 브라운필드 워크플로우 (기존 코드베이스) + +``` + /gsd-map-codebase + │ + ├── Stack Mapper -> codebase/STACK.md + ├── Arch Mapper -> codebase/ARCHITECTURE.md + ├── Convention Mapper -> codebase/CONVENTIONS.md + └── Concern Mapper -> codebase/CONCERNS.md + │ + ┌───────▼──────────┐ + │ /gsd-new-project │ <- Questions focus on what you're ADDING + └──────────────────┘ +``` + +--- + +## 명령어 레퍼런스 + +### 핵심 워크플로우 + +| 명령어 | 목적 | 사용 시점 | +|--------|------|----------| +| `/gsd-new-project` | 전체 프로젝트 초기화: 질문, 조사, 요구사항, 로드맵 | 새 프로젝트 시작 시 | +| `/gsd-new-project --auto @idea.md` | 문서에서 자동 초기화 | PRD나 아이디어 문서가 준비된 경우 | +| `/gsd-discuss-phase [N]` | 구현 결정사항 캡처 | 계획 전 구축 방식을 결정할 때 | +| `/gsd-ui-phase [N]` | UI 설계 계약 생성 | discuss-phase 이후, plan-phase 이전 (프론트엔드 페이즈) | +| `/gsd-plan-phase [N]` | 조사 + 계획 + 검증 | 페이즈 실행 전 | +| `/gsd-execute-phase ` | 병렬 웨이브로 모든 계획 실행 | 계획이 완료된 후 | +| `/gsd-verify-work [N]` | 자동 진단을 포함한 수동 UAT | 실행 완료 후 | +| `/gsd-ship [N]` | 검증된 작업으로 PR 생성 | 검증 통과 후 | +| `/gsd-fast ` | 계획을 완전히 건너뛰는 인라인 간단 작업 | 오타 수정, 설정 변경, 소규모 리팩터링 | +| `/gsd-next` | 상태 자동 감지 및 다음 단계 실행 | 언제든 — "다음에 무엇을 해야 하나?" | +| `/gsd-ui-review [N]` | 6개 기둥 기반 시각적 감사 소급 수행 | 실행 또는 verify-work 이후 (프론트엔드 프로젝트) | +| `/gsd-audit-milestone` | 마일스톤이 완료 정의를 충족했는지 검증 | 마일스톤 완료 전 | +| `/gsd-complete-milestone` | 마일스톤 아카이브 및 릴리스 태그 생성 | 모든 페이즈 검증 완료 시 | +| `/gsd-new-milestone [name]` | 다음 버전 사이클 시작 | 마일스톤 완료 후 | + +### 탐색 + +| 명령어 | 목적 | 사용 시점 | +|--------|------|----------| +| `/gsd-progress` | 상태 및 다음 단계 표시 | 언제든 -- "지금 어디 있나?" | +| `/gsd-resume-work` | 마지막 세션의 전체 컨텍스트 복원 | 새 세션 시작 시 | +| `/gsd-pause-work` | 구조화된 핸드오프 저장 (HANDOFF.json + continue-here.md) | 페이즈 중간에 중단할 때 | +| `/gsd-session-report` | 작업 및 결과가 포함된 세션 요약 생성 | 세션 종료 시, 이해관계자 공유 시 | +| `/gsd-help` | 모든 명령어 표시 | 빠른 레퍼런스 | +| `/gsd-update` | 변경 로그 미리보기와 함께 GSD 업데이트 | 새 버전 확인 시 | +| `/gsd-join-discord` | Discord 커뮤니티 초대 링크 열기 | 질문이나 커뮤니티 참여 시 | + +### 페이즈 관리 + +| 명령어 | 목적 | 사용 시점 | +|--------|------|----------| +| `/gsd-add-phase` | 로드맵에 새 페이즈 추가 | 초기 계획 후 범위가 늘어날 때 | +| `/gsd-insert-phase [N]` | 긴급 작업 삽입 (소수점 번호 체계) | 마일스톤 중간의 긴급 수정 시 | +| `/gsd-remove-phase [N]` | 미래 페이즈 제거 및 재번호 | 기능 범위 축소 시 | +| `/gsd-list-phase-assumptions [N]` | OpenCode의 예상 접근 방식 미리 확인 | 계획 전 방향 검증 시 | +| `/gsd-plan-milestone-gaps` | 감사 갭을 위한 페이즈 생성 | 감사에서 누락 항목이 발견된 후 | +| `/gsd-research-phase [N]` | 심층 에코시스템 조사만 수행 | 복잡하거나 익숙하지 않은 도메인 | + +### 브라운필드 및 유틸리티 + +| 명령어 | 목적 | 사용 시점 | +|--------|------|----------| +| `/gsd-map-codebase` | 기존 코드베이스 분석 | 기존 코드에서 `/gsd-new-project` 실행 전 | +| `/gsd-quick` | GSD 보증을 갖춘 임시 작업 | 버그 수정, 소규모 기능, 설정 변경 | +| `/gsd-debug [desc]` | 지속적인 상태를 유지하는 체계적인 디버깅 | 문제가 발생했을 때 | +| `/gsd-forensics` | 워크플로우 실패에 대한 진단 보고서 | 상태, 아티팩트, git 히스토리가 손상된 것 같을 때 | +| `/gsd-add-todo [desc]` | 나중을 위한 아이디어 캡처 | 세션 중에 생각이 날 때 | +| `/gsd-check-todos` | 보류 중인 할 일 목록 | 캡처된 아이디어 검토 시 | +| `/gsd-settings` | 워크플로우 토글 및 모델 프로필 설정 | 모델 변경, 에이전트 토글 시 | +| `/gsd-set-profile ` | 빠른 프로필 전환 | 비용/품질 트레이드오프 변경 시 | +| `/gsd-reapply-patches` | 업데이트 후 로컬 수정사항 복원 | 로컬 편집이 있는 상태에서 `/gsd-update` 이후 | + +### 코드 품질 및 리뷰 + +| 명령어 | 목적 | 사용 시점 | +|--------|------|----------| +| `/gsd-review --phase N` | 외부 CLI를 통한 교차 AI 동료 리뷰 | 실행 전 계획 검증 시 | +| `/gsd-pr-branch` | `.planning/` 커밋을 필터링한 깔끔한 PR 브랜치 | 계획 없는 diff로 PR 생성 전 | +| `/gsd-audit-uat` | 모든 페이즈의 검증 부채 감사 | 마일스톤 완료 전 | + +### 백로그 및 스레드 + +| 명령어 | 목적 | 사용 시점 | +|--------|------|----------| +| `/gsd-add-backlog ` | 백로그 파킹 롯에 아이디어 추가 (999.x) | 활성 계획에 준비되지 않은 아이디어 | +| `/gsd-review-backlog` | 백로그 항목 승격/유지/제거 | 새 마일스톤 전 우선순위 결정 시 | +| `/gsd-plant-seed ` | 트리거 조건이 있는 미래 지향적인 아이디어 | 미래 마일스톤에서 표면화되어야 할 아이디어 | +| `/gsd-thread [name]` | 지속적인 컨텍스트 스레드 | 페이즈 구조 밖의 교차 세션 작업 | + +--- + +## 설정 레퍼런스 + +GSD는 프로젝트 설정을 `.planning/config.json`에 저장합니다. `/gsd-new-project` 중에 설정하거나 나중에 `/gsd-settings`로 업데이트할 수 있습니다. + +### 전체 config.json 스키마 + +```json +{ + "mode": "interactive", + "granularity": "standard", + "model_profile": "balanced", + "planning": { + "commit_docs": true, + "search_gitignored": false + }, + "workflow": { + "research": true, + "plan_check": true, + "verifier": true, + "nyquist_validation": true, + "ui_phase": true, + "ui_safety_gate": true, + "research_before_questions": false, + "discuss_mode": "standard", + "skip_discuss": false + }, + "resolve_model_ids": "anthropic", + "hooks": { + "context_warnings": true, + "workflow_guard": false + }, + "git": { + "branching_strategy": "none", + "phase_branch_template": "gsd/phase-{phase}-{slug}", + "milestone_branch_template": "gsd/{milestone}-{slug}", + "quick_branch_template": null + } +} +``` + +### 핵심 설정 + +| 설정 | 옵션 | 기본값 | 제어 대상 | +|------|------|--------|----------| +| `mode` | `interactive`, `yolo` | `interactive` | `yolo`는 결정을 자동 승인하고 `interactive`는 각 단계에서 확인합니다 | +| `granularity` | `coarse`, `standard`, `fine` | `standard` | 페이즈 세분화: 범위를 얼마나 세밀하게 나눌지 (3-5, 5-8, 또는 8-12 페이즈) | +| `model_profile` | `quality`, `balanced`, `budget`, `inherit` | `balanced` | 각 에이전트의 모델 티어 (아래 표 참고) | + +### 계획 설정 + +| 설정 | 옵션 | 기본값 | 제어 대상 | +|------|------|--------|----------| +| `planning.commit_docs` | `true`, `false` | `true` | `.planning/` 파일을 git에 커밋할지 여부 | +| `planning.search_gitignored` | `true`, `false` | `false` | 광범위한 검색에 `--no-ignore`를 추가하여 `.planning/` 포함 | + +> **참고:** `.planning/`이 `.gitignore`에 있으면 설정 값에 관계없이 `commit_docs`는 자동으로 `false`가 됩니다. + +### 워크플로우 토글 + +| 설정 | 옵션 | 기본값 | 제어 대상 | +|------|------|--------|----------| +| `workflow.research` | `true`, `false` | `true` | 계획 전 도메인 조사 | +| `workflow.plan_check` | `true`, `false` | `true` | 계획 검증 루프 (최대 3회 반복) | +| `workflow.verifier` | `true`, `false` | `true` | 페이즈 목표에 대한 실행 후 검증 | +| `workflow.nyquist_validation` | `true`, `false` | `true` | plan-phase 중 검증 아키텍처 조사 및 8번째 plan-check 차원 | +| `workflow.ui_phase` | `true`, `false` | `true` | 프론트엔드 페이즈를 위한 UI 설계 계약 생성 | +| `workflow.ui_safety_gate` | `true`, `false` | `true` | plan-phase가 프론트엔드 페이즈에서 /gsd-ui-phase 실행을 유도합니다 | +| `workflow.research_before_questions` | `true`, `false` | `false` | 토론 질문 이후가 아닌 이전에 조사를 실행합니다 | +| `workflow.discuss_mode` | `standard`, `assumptions` | `standard` | 토론 방식: 개방형 질문 vs. 코드베이스 기반 가정 | +| `workflow.skip_discuss` | `true`, `false` | `false` | 자율 모드에서 discuss-phase를 완전히 건너뜁니다. ROADMAP 페이즈 목표에서 최소한의 CONTEXT.md를 작성합니다 | + +### 훅 설정 + +| 설정 | 옵션 | 기본값 | 제어 대상 | +|------|------|--------|----------| +| `hooks.context_warnings` | `true`, `false` | `true` | 컨텍스트 윈도우 사용량 경고 | +| `hooks.workflow_guard` | `true`, `false` | `false` | GSD 워크플로우 컨텍스트 밖의 파일 편집 시 경고 | + +익숙한 도메인에서 페이즈를 빠르게 진행하거나 토큰을 절약할 때 워크플로우 토글을 비활성화하세요. + +### Git 브랜칭 + +| 설정 | 옵션 | 기본값 | 제어 대상 | +|------|------|--------|----------| +| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | 브랜치 생성 시점과 방법 | +| `git.phase_branch_template` | 템플릿 문자열 | `gsd/phase-{phase}-{slug}` | phase 전략의 브랜치 이름 | +| `git.milestone_branch_template` | 템플릿 문자열 | `gsd/{milestone}-{slug}` | milestone 전략의 브랜치 이름 | +| `git.quick_branch_template` | 템플릿 문자열 또는 `null` | `null` | `/gsd-quick` 작업의 선택적 브랜치 이름 | + +**브랜칭 전략 설명.** + +| 전략 | 브랜치 생성 | 범위 | 적합한 경우 | +|------|------------|------|------------| +| `none` | 생성 안 함 | N/A | 개인 개발, 간단한 프로젝트 | +| `phase` | 각 `execute-phase` 시 | 페이즈당 하나의 브랜치 | 페이즈별 코드 리뷰, 세분화된 롤백 | +| `milestone` | 첫 `execute-phase` 시 | 모든 페이즈가 하나의 브랜치 공유 | 릴리스 브랜치, 버전별 PR | + +**템플릿 변수:** `{phase}` = 0 패딩된 번호 (예: "03"), `{slug}` = 소문자 하이픈 이름, `{milestone}` = 버전 (예: "v1.0"), `{num}` / `{quick}` = 빠른 작업 ID (예: "260317-abc"). + +빠른 작업 브랜칭 예시: + +```json +"git": { + "quick_branch_template": "gsd/quick-{num}-{slug}" +} +``` + +### 모델 프로필 (에이전트별 분류) + +| 에이전트 | `quality` | `balanced` | `budget` | `inherit` | +|----------|-----------|------------|----------|-----------| +| gsd-planner | Opus | Opus | Sonnet | Inherit | +| gsd-roadmapper | Opus | Sonnet | Sonnet | Inherit | +| gsd-executor | Opus | Sonnet | Sonnet | Inherit | +| gsd-phase-researcher | Opus | Sonnet | Haiku | Inherit | +| gsd-project-researcher | Opus | Sonnet | Haiku | Inherit | +| gsd-research-synthesizer | Sonnet | Sonnet | Haiku | Inherit | +| gsd-debugger | Opus | Sonnet | Sonnet | Inherit | +| gsd-codebase-mapper | Sonnet | Haiku | Haiku | Inherit | +| gsd-verifier | Sonnet | Sonnet | Haiku | Inherit | +| gsd-plan-checker | Sonnet | Sonnet | Haiku | Inherit | +| gsd-integration-checker | Sonnet | Sonnet | Haiku | Inherit | + +**프로필 철학.** +- **quality** -- 모든 의사결정 에이전트에 Opus를 사용하고 읽기 전용 검증에 Sonnet을 사용합니다. 할당량이 충분하고 작업이 중요할 때 사용합니다. +- **balanced** -- 아키텍처 결정이 이루어지는 계획에만 Opus를 사용하고 나머지는 Sonnet을 사용합니다. 합당한 이유로 기본값입니다. +- **budget** -- 코드를 작성하는 모든 것에 Sonnet을 사용하고 조사 및 검증에 Haiku를 사용합니다. 대량 작업이나 덜 중요한 페이즈에 사용합니다. +- **inherit** -- 모든 에이전트가 현재 세션 모델을 사용합니다. 동적으로 모델을 전환할 때 (예: OpenCode `/model`) 또는 예상치 못한 API 비용을 방지하기 위해 비Anthropic 공급자 (OpenRouter, 로컬 모델)와 함께 OpenCode를 사용할 때 적합합니다. 비OpenCode 런타임 (Codex, OpenCode, Gemini CLI)의 경우 설치 프로그램이 자동으로 `resolve_model_ids: "omit"`을 설정합니다 — [비OpenCode 런타임](#비OpenCode-런타임-codex-opencode-gemini-cli-사용)을 참고하세요. + +--- + +## 사용 예시 + +### 새 프로젝트 (전체 사이클) + +```bash +OpenCode --dangerously-skip-permissions +/gsd-new-project # Answer questions, configure, approve roadmap +/new +/gsd-discuss-phase 1 # Lock in your preferences +/gsd-ui-phase 1 # Design contract (frontend phases) +/gsd-plan-phase 1 # Research + plan + verify +/gsd-execute-phase 1 # Parallel execution +/gsd-verify-work 1 # Manual UAT +/gsd-ship 1 # Create PR from verified work +/gsd-ui-review 1 # Visual audit (frontend phases) +/new +/gsd-next # Auto-detect and run next step +... +/gsd-audit-milestone # Check everything shipped +/gsd-complete-milestone # Archive, tag, done +/gsd-session-report # Generate session summary +``` + +### 기존 문서로 새 프로젝트 시작 + +```bash +/gsd-new-project --auto @prd.md # Auto-runs research/requirements/roadmap from your doc +/new +/gsd-discuss-phase 1 # Normal flow from here +``` + +### 기존 코드베이스 + +```bash +/gsd-map-codebase # Analyze what exists (parallel agents) +/gsd-new-project # Questions focus on what you're ADDING +# (normal phase workflow from here) +``` + +### 빠른 버그 수정 + +```bash +/gsd-quick +> "Fix the login button not responding on mobile Safari" +``` + +### 휴식 후 재개 + +```bash +/gsd-progress # See where you left off and what's next +# or +/gsd-resume-work # Full context restoration from last session +``` + +### 릴리스 준비 + +```bash +/gsd-audit-milestone # Check requirements coverage, detect stubs +/gsd-plan-milestone-gaps # If audit found gaps, create phases to close them +/gsd-complete-milestone # Archive, tag, done +``` + +### 속도 vs 품질 프리셋 + +| 시나리오 | Mode | Granularity | Profile | Research | Plan Check | Verifier | +|---------|------|-------------|---------|----------|------------|---------| +| 프로토타이핑 | `yolo` | `coarse` | `budget` | 끄기 | 끄기 | 끄기 | +| 일반 개발 | `interactive` | `standard` | `balanced` | 켜기 | 켜기 | 켜기 | +| 프로덕션 | `interactive` | `fine` | `quality` | 켜기 | 켜기 | 켜기 | + +**자율 모드에서 discuss-phase 건너뛰기:** PROJECT.md에 선호도가 이미 충분히 캡처된 `yolo` 모드에서 실행할 때 `/gsd-settings`에서 `workflow.skip_discuss: true`로 설정하세요. 이렇게 하면 discuss-phase를 완전히 우회하고 ROADMAP 페이즈 목표에서 파생된 최소한의 CONTEXT.md를 작성합니다. PROJECT.md와 관례가 충분히 포괄적이어서 토론이 새로운 정보를 제공하지 않을 때 유용합니다. + +### 마일스톤 중간 범위 변경 + +```bash +/gsd-add-phase # Append a new phase to the roadmap +# or +/gsd-insert-phase 3 # Insert urgent work between phases 3 and 4 +# or +/gsd-remove-phase 7 # Descope phase 7 and renumber +``` + +### 멀티 프로젝트 워크스페이스 + +격리된 GSD 상태로 여러 저장소나 기능을 병렬로 작업합니다. + +```bash +# Create a workspace with repos from your monorepo +/gsd-new-workspace --name feature-b --repos hr-ui,ZeymoAPI + +# Feature branch isolation — worktree of current repo with its own .planning/ +/gsd-new-workspace --name feature-b --repos . + +# Then cd into the workspace and initialize GSD +cd ~/gsd-workspaces/feature-b +/gsd-new-project + +# List and manage workspaces +/gsd-list-workspaces +/gsd-remove-workspace feature-b +``` + +각 워크스페이스는 다음을 포함합니다. +- 자체 `.planning/` 디렉터리 (원본 저장소와 완전히 독립) +- 지정된 저장소의 git worktree (기본값) 또는 클론 +- 멤버 저장소를 추적하는 `WORKSPACE.md` 매니페스트 + +--- + +## 문제 해결 + +### "Project already initialized" + +`.planning/PROJECT.md`가 이미 존재하는데 `/gsd-new-project`를 실행했습니다. 이것은 안전 검사입니다. 처음부터 다시 시작하려면 먼저 `.planning/` 디렉터리를 삭제하세요. + +### 긴 세션 중 컨텍스트 저하 + +주요 명령어 사이에 컨텍스트 윈도우를 지우세요: OpenCode에서 `/new`를 사용합니다. GSD는 새로운 컨텍스트를 기반으로 설계되었습니다 — 모든 서브에이전트는 깨끗한 200K 윈도우를 받습니다. 메인 세션의 품질이 저하되면 지우고 `/gsd-resume-work` 또는 `/gsd-progress`를 사용하여 상태를 복원하세요. + +### 계획이 잘못되거나 맞지 않는 경우 + +계획 전에 `/gsd-discuss-phase [N]`을 실행하세요. 대부분의 계획 품질 문제는 `CONTEXT.md`가 있었다면 방지할 수 있었던 가정을 OpenCode가 세우기 때문에 발생합니다. `/gsd-list-phase-assumptions [N]`을 실행하여 계획에 동의하기 전에 OpenCode가 무엇을 하려는지 확인할 수도 있습니다. + +### 실행이 실패하거나 스텁을 생성하는 경우 + +계획이 너무 야심차지 않은지 확인하세요. 계획에는 최대 2-3개의 작업이 있어야 합니다. 작업이 너무 크면 단일 컨텍스트 윈도우에서 안정적으로 처리할 수 있는 범위를 초과합니다. 더 작은 범위로 재계획하세요. + +### 현재 위치를 잃어버린 경우 + +`/gsd-progress`를 실행하세요. 모든 상태 파일을 읽고 현재 위치와 다음에 할 일을 정확히 알려줍니다. + +### 실행 후 변경이 필요한 경우 + +`/gsd-execute-phase`를 다시 실행하지 마세요. 목표를 정확히 수정하려면 `/gsd-quick`을 사용하거나 UAT를 통해 체계적으로 문제를 식별하고 수정하려면 `/gsd-verify-work`를 사용하세요. + +### 모델 비용이 너무 높은 경우 + +예산 프로필로 전환하세요: `/gsd-set-profile budget`. 도메인이 익숙하다면 (또는 OpenCode에게 익숙하다면) `/gsd-settings`에서 조사 및 plan-check 에이전트를 비활성화하세요. + +### 비OpenCode 런타임 사용 (Codex, OpenCode, Gemini CLI) + +비OpenCode 런타임용으로 GSD를 설치했다면 설치 프로그램이 이미 모든 에이전트가 런타임의 기본 모델을 사용하도록 모델 해석을 구성했습니다. 수동 설정이 필요하지 않습니다. 구체적으로 설치 프로그램은 config에 `resolve_model_ids: "omit"`을 설정하여 GSD가 Anthropic 모델 ID 해석을 건너뛰고 런타임이 자체 기본 모델을 선택하도록 합니다. + +비OpenCode 런타임에서 에이전트별로 다른 모델을 할당하려면 런타임이 인식하는 완전한 자격을 갖춘 모델 ID와 함께 `.planning/config.json`에 `model_overrides`를 추가하세요. + +```json +{ + "resolve_model_ids": "omit", + "model_overrides": { + "gsd-planner": "o3", + "gsd-executor": "o4-mini", + "gsd-debugger": "o3" + } +} +``` + +설치 프로그램은 Gemini CLI, OpenCode, Codex에 대해 `resolve_model_ids: "omit"`을 자동으로 구성합니다. 비OpenCode 런타임을 수동으로 설정하는 경우 직접 `.planning/config.json`에 추가하세요. + +전체 설명은 [Configuration Reference](CONFIGURATION.md#non-OpenCode-runtimes-codex-opencode-gemini-cli)를 참고하세요. + +### 비Anthropic 공급자와 함께 OpenCode 사용 (OpenRouter, 로컬) + +GSD 서브에이전트가 Anthropic 모델을 호출하는데 OpenRouter나 로컬 공급자를 통해 비용을 지불하고 있다면 `inherit` 프로필로 전환하세요: `/gsd-set-profile inherit`. 이렇게 하면 모든 에이전트가 특정 Anthropic 모델 대신 현재 세션 모델을 사용합니다. `/gsd-settings` → Model Profile → Inherit도 참고하세요. + +### 민감하거나 비공개 프로젝트에서 작업하는 경우 + +`/gsd-new-project` 중에 또는 `/gsd-settings`에서 `commit_docs: false`로 설정하세요. `.planning/`을 `.gitignore`에 추가하세요. 계획 아티팩트는 로컬에 유지되며 git에 절대 포함되지 않습니다. + +### GSD 업데이트가 로컬 변경사항을 덮어쓴 경우 + +v1.17부터 설치 프로그램이 로컬로 수정된 파일을 `gsd-local-patches/`에 백업합니다. 변경사항을 다시 병합하려면 `/gsd-reapply-patches`를 실행하세요. + +### 워크플로우 진단 (`/gsd-forensics`) + +워크플로우가 명확하지 않은 방식으로 실패할 때 — 계획이 존재하지 않는 파일을 참조하거나 실행이 예상치 못한 결과를 생성하거나 상태가 손상된 것 같을 때 — `/gsd-forensics`를 실행하여 진단 보고서를 생성하세요. + +**검사 항목.** +- Git 히스토리 이상 (고아 커밋, 예상치 못한 브랜치 상태, rebase 아티팩트) +- 아티팩트 무결성 (누락되거나 잘못된 계획 파일, 끊어진 교차 참조) +- 상태 불일치 (실제 파일 존재 여부 대비 ROADMAP 상태, 설정 드리프트) + +**출력:** 발견사항과 권장 수정 단계가 포함된 `.planning/forensics/`의 진단 보고서. + +### 서브에이전트가 실패한 것 같지만 작업이 완료된 경우 + +OpenCode 분류 버그에 대한 알려진 해결 방법이 있습니다. GSD의 오케스트레이터 (execute-phase, quick)는 실패를 보고하기 전에 실제 출력을 현장 확인합니다. 실패 메시지가 표시되었지만 커밋이 이루어진 경우 `git log`를 확인하세요 — 작업이 성공했을 수 있습니다. + +### 병렬 실행으로 인한 빌드 잠금 오류 + +병렬 웨이브 실행 중에 pre-commit 훅 실패, cargo lock 경합, 또는 30분 이상의 실행 시간이 발생한다면 여러 에이전트가 동시에 빌드 도구를 실행하기 때문입니다. GSD는 v1.26부터 이를 자동으로 처리합니다 — 병렬 에이전트는 커밋에 `--no-verify`를 사용하고 오케스트레이터가 각 웨이브 후 한 번 훅을 실행합니다. 이전 버전을 사용하는 경우 프로젝트의 `AGENTS.md`에 다음을 추가하세요. + +```markdown +## Git Commit Rules for Agents +All subagent/executor commits MUST use `--no-verify`. +``` + +병렬 실행을 완전히 비활성화하려면: `/gsd-settings` → `parallelization.enabled`를 `false`로 설정합니다. + +### Windows: 보호된 디렉터리에서 설치 충돌 + +Windows에서 설치 프로그램이 `EPERM: operation not permitted, scandir`으로 충돌하는 경우 OS 보호 디렉터리 (예: Chromium 브라우저 프로필) 때문입니다. v1.24부터 수정되었으니 최신 버전으로 업데이트하세요. 해결 방법으로 설치 프로그램을 실행하기 전에 문제가 되는 디렉터리를 임시로 이름을 변경하세요. + +--- + +## 복구 빠른 레퍼런스 + +| 문제 | 해결 방법 | +|------|----------| +| 컨텍스트 손실 / 새 세션 | `/gsd-resume-work` 또는 `/gsd-progress` | +| 페이즈가 잘못됨 | 페이즈 커밋에 `git revert` 후 재계획 | +| 범위 변경 필요 | `/gsd-add-phase`, `/gsd-insert-phase`, 또는 `/gsd-remove-phase` | +| 마일스톤 감사에서 갭 발견 | `/gsd-plan-milestone-gaps` | +| 무언가 고장남 | `/gsd-debug "description"` | +| 워크플로우 상태 손상 의심 | `/gsd-forensics` | +| 빠른 목표 수정 | `/gsd-quick` | +| 계획이 비전과 맞지 않음 | `/gsd-discuss-phase [N]` 후 재계획 | +| 비용이 높아짐 | `/gsd-set-profile budget` 및 `/gsd-settings`에서 에이전트 비활성화 | +| 업데이트가 로컬 변경사항 파괴 | `/gsd-reapply-patches` | +| 이해관계자를 위한 세션 요약 필요 | `/gsd-session-report` | +| 다음 단계를 모르겠음 | `/gsd-next` | +| 병렬 실행 빌드 오류 | GSD 업데이트 또는 `parallelization.enabled: false` 설정 | + +--- + +## 프로젝트 파일 구조 + +참고로 GSD가 프로젝트에 생성하는 파일 구조입니다. + +``` +.planning/ + PROJECT.md # Project vision and context (always loaded) + REQUIREMENTS.md # Scoped v1/v2 requirements with IDs + ROADMAP.md # Phase breakdown with status tracking + STATE.md # Decisions, blockers, session memory + config.json # Workflow configuration + MILESTONES.md # Completed milestone archive + HANDOFF.json # Structured session handoff (from /gsd-pause-work) + research/ # Domain research from /gsd-new-project + reports/ # Session reports (from /gsd-session-report) + todos/ + pending/ # Captured ideas awaiting work + done/ # Completed todos + debug/ # Active debug sessions + resolved/ # Archived debug sessions + codebase/ # Brownfield codebase mapping (from /gsd-map-codebase) + phases/ + XX-phase-name/ + XX-YY-PLAN.md # Atomic execution plans + XX-YY-SUMMARY.md # Execution outcomes and decisions + CONTEXT.md # Your implementation preferences + RESEARCH.md # Ecosystem research findings + VERIFICATION.md # Post-execution verification results + XX-UI-SPEC.md # UI design contract (from /gsd-ui-phase) + XX-UI-REVIEW.md # Visual audit scores (from /gsd-ui-review) + ui-reviews/ # Screenshots from /gsd-ui-review (gitignored) +``` diff --git a/gsd-opencode/docs/ko-KR/context-monitor.md b/gsd-opencode/docs/ko-KR/context-monitor.md new file mode 100644 index 0000000..9c68991 --- /dev/null +++ b/gsd-opencode/docs/ko-KR/context-monitor.md @@ -0,0 +1,115 @@ +# 컨텍스트 윈도우 모니터 + +에이전트의 컨텍스트 윈도우 사용량이 높을 때 경고를 주는 post-tool 훅입니다 (OpenCode의 경우 `PostToolUse`, Gemini CLI의 경우 `AfterTool`). + +## 문제 + +상태바(statusline)는 **사용자**에게 컨텍스트 사용량을 보여주지만 **에이전트** 자체는 컨텍스트 한계를 인식하지 못합니다. 컨텍스트가 부족해지면 에이전트는 한계에 부딪힐 때까지 작업을 계속 진행하며 상태가 저장되지 않은 채 작업 도중에 멈출 수 있습니다. + +## 동작 방식 + +1. statusline 훅이 컨텍스트 메트릭을 `/tmp/OpenCode-ctx-{session_id}.json`에 기록합니다. +2. 각 도구 사용 후 context monitor가 해당 메트릭을 읽습니다. +3. 남은 컨텍스트가 임계값 아래로 떨어지면 `additionalContext`로 경고를 주입합니다. +4. 에이전트는 대화에서 경고를 받고 그에 맞게 대응할 수 있습니다. + +## 임계값 + +| 레벨 | 남은 비율 | 에이전트 동작 | +|------|-----------|---------------| +| Normal | > 35% | 경고 없음 | +| WARNING | <= 35% | 현재 작업 마무리, 새로운 복잡한 작업 시작 금지 | +| CRITICAL | <= 25% | 즉시 중단 후 상태 저장 (`/gsd-pause-work`) | + +## Debounce + +에이전트에게 반복적인 경고가 쌓이는 것을 방지하기 위한 동작입니다. +- 첫 번째 경고는 항상 즉시 발생합니다. +- 이후 경고는 5번의 도구 사용 간격이 필요합니다. +- 심각도 상승 (WARNING → CRITICAL) 시에는 debounce를 우회합니다. + +## 아키텍처 + +``` +Statusline Hook (gsd-statusline.js) + | 기록 + v +/tmp/OpenCode-ctx-{session_id}.json + ^ 읽기 + | +Context Monitor (gsd-context-monitor.js, PostToolUse/AfterTool) + | 주입 + v +additionalContext -> 에이전트가 경고를 받음 +``` + +브리지 파일은 단순한 JSON 객체입니다. + +```json +{ + "session_id": "abc123", + "remaining_percentage": 28.5, + "used_pct": 71, + "timestamp": 1708200000 +} +``` + +## GSD와의 통합 + +GSD의 `/gsd-pause-work` 명령어는 실행 상태를 저장합니다. WARNING 메시지는 해당 명령어 사용을 권장하며 CRITICAL 메시지는 즉각적인 상태 저장을 지시합니다. + +## 설정 + +두 훅 모두 `npx gsd-opencode` 설치 중에 자동으로 등록됩니다. + +- **Statusline** (브리지 파일 기록): settings.json에 `statusLine`으로 등록 +- **Context Monitor** (브리지 파일 읽기): settings.json에 `PostToolUse` 훅으로 등록 (Gemini의 경우 `AfterTool`) + +`$HOME/.config/opencode/settings.json`에 수동으로 등록하는 방법 (OpenCode): + +```json +{ + "statusLine": { + "type": "command", + "command": "node $HOME/.config/opencode/hooks/gsd-statusline.js" + }, + "hooks": { + "PostToolUse": [ + { + "hooks": [ + { + "type": "command", + "command": "node $HOME/.config/opencode/hooks/gsd-context-monitor.js" + } + ] + } + ] + } +} +``` + +Gemini CLI (`~/.gemini/settings.json`)의 경우 `PostToolUse` 대신 `AfterTool`을 사용합니다. + +```json +{ + "hooks": { + "AfterTool": [ + { + "hooks": [ + { + "type": "command", + "command": "node ~/.gemini/hooks/gsd-context-monitor.js" + } + ] + } + ] + } +} +``` + +## 안전성 + +- 훅은 모든 동작을 try/catch로 감싸며 오류 발생 시 조용히 종료합니다. +- 도구 실행을 절대 차단하지 않습니다. 모니터에 문제가 생겨도 에이전트 워크플로우가 중단되지 않습니다. +- 60초 이상 된 오래된 메트릭은 무시됩니다. +- 누락된 브리지 파일은 정상적으로 처리됩니다 (서브에이전트, 새 세션 등의 경우). diff --git a/gsd-opencode/docs/ko-KR/superpowers/plans/2026-03-18-materialize-new-project-config.md b/gsd-opencode/docs/ko-KR/superpowers/plans/2026-03-18-materialize-new-project-config.md new file mode 100644 index 0000000..164e0d4 --- /dev/null +++ b/gsd-opencode/docs/ko-KR/superpowers/plans/2026-03-18-materialize-new-project-config.md @@ -0,0 +1,699 @@ +# 초기화 시 new-project config 완전 구체화 + +> **에이전트 작업자를 위한 안내:** 필수 하위 기술: superpowers:subagent-driven-development(권장) 또는 superpowers:executing-plans를 사용하여 이 계획을 작업 단위로 구현하세요. 단계는 체크박스(`- [ ]`) 형식으로 진행 상황을 추적합니다. + +**목표:** `/gsd-new-project`가 `.planning/config.json`을 생성할 때, 파일에 사용자가 선택한 6개 키만이 아닌 모든 유효한 기본값이 포함되도록 하여 개발자가 소스 코드를 읽지 않고도 모든 설정을 확인할 수 있게 합니다. + +**아키텍처:** 새 프로젝트의 전체 config에 대한 단일 진실 공급원으로서 `config.cjs`에 단일 JS 함수 `buildNewProjectConfig(cwd, userChoices)`를 추가합니다. CLI 명령어 `config-new-project`로 노출합니다. 부분적인 JSON을 인라인으로 작성하는 대신 이 명령어를 호출하도록 `new-project.md` 워크플로우를 업데이트합니다. + +**기술 스택:** Node.js/CommonJS, 기존 gsd-tools CLI, 테스트에는 `node:test`. + +--- + +## 배경: 현재 상태 + +`new-project.md` Step 5는 이 부분적인 config를 작성합니다(AI가 템플릿을 채움): + +```json +{ + "mode": "...", "granularity": "...", "parallelization": "...", + "commit_docs": "...", "model_profile": "...", + "workflow": { "research", "plan_check", "verifier", "nyquist_validation" } +} +``` + +런타임에 `loadConfig()`가 자동으로 해석하는 누락된 키들: + +- `search_gitignored: false` +- `brave_search: false` (또는 환경 감지 시 `true`) +- `git.branching_strategy: "none"` +- `git.phase_branch_template: "gsd/phase-{phase}-{slug}"` +- `git.milestone_branch_template: "gsd/{milestone}-{slug}"` + +처음부터 존재해야 하는 전체 config: + +```json +{ + "mode": "yolo|interactive", + "granularity": "coarse|standard|fine", + "model_profile": "balanced", + "commit_docs": true, + "parallelization": true, + "search_gitignored": false, + "brave_search": false, + "git": { + "branching_strategy": "none", + "phase_branch_template": "gsd/phase-{phase}-{slug}", + "milestone_branch_template": "gsd/{milestone}-{slug}" + }, + "workflow": { + "research": true, + "plan_check": true, + "verifier": true, + "nyquist_validation": true + } +} +``` + +--- + +## 파일 맵 + +| 파일 | 액션 | 목적 | +|------|--------|---------| +| `get-shit-done/bin/lib/config.cjs` | 수정 | `buildNewProjectConfig()` + `cmdConfigNewProject()` 추가 | +| `get-shit-done/bin/gsd-tools.cjs` | 수정 | `config-new-project` case 등록 + usage 문자열 업데이트 | +| `get-shit-done/workflows/new-project.md` | 수정 | Steps 2a + 5: 인라인 JSON 작성을 CLI 호출로 교체 | +| `tests/config.test.cjs` | 수정 | `config-new-project` 테스트 스위트 추가 | + +--- + +## 작업 1: config.cjs에 `buildNewProjectConfig`와 `cmdConfigNewProject` 추가 + +**파일.** + +- 수정: `get-shit-done/bin/lib/config.cjs` + +- [ ] **Step 1.1: 실패하는 테스트 먼저 작성** + +`tests/config.test.cjs`에 추가(`config-get` 스위트 뒤, `module.exports` 앞): + +```js +// ─── config-new-project ────────────────────────────────────────────────────── + +describe('config-new-project command', () => { + let tmpDir; + + beforeEach(() => { + tmpDir = createTempProject(); + }); + + afterEach(() => { + cleanup(tmpDir); + }); + + test('creates full config with all expected top-level and nested keys', () => { + const choices = JSON.stringify({ + mode: 'interactive', + granularity: 'standard', + parallelization: true, + commit_docs: true, + model_profile: 'balanced', + workflow: { research: true, plan_check: true, verifier: true, nyquist_validation: true }, + }); + const result = runGsdTools(['config-new-project', choices], tmpDir); + assert.ok(result.success, `Command failed: ${result.error}`); + + const config = readConfig(tmpDir); + + // 사용자 선택값 확인 + assert.strictEqual(config.mode, 'interactive'); + assert.strictEqual(config.granularity, 'standard'); + assert.strictEqual(config.parallelization, true); + assert.strictEqual(config.commit_docs, true); + assert.strictEqual(config.model_profile, 'balanced'); + + // 기본값이 구체화되었는지 확인 + assert.strictEqual(typeof config.search_gitignored, 'boolean'); + assert.strictEqual(typeof config.brave_search, 'boolean'); + + // git 섹션에 세 가지 키가 모두 존재하는지 확인 + assert.ok(config.git && typeof config.git === 'object', 'git section should exist'); + assert.strictEqual(config.git.branching_strategy, 'none'); + assert.strictEqual(config.git.phase_branch_template, 'gsd/phase-{phase}-{slug}'); + assert.strictEqual(config.git.milestone_branch_template, 'gsd/{milestone}-{slug}'); + + // workflow 섹션에 네 가지 키가 모두 존재하는지 확인 + assert.ok(config.workflow && typeof config.workflow === 'object', 'workflow section should exist'); + assert.strictEqual(config.workflow.research, true); + assert.strictEqual(config.workflow.plan_check, true); + assert.strictEqual(config.workflow.verifier, true); + assert.strictEqual(config.workflow.nyquist_validation, true); + }); + + test('user choices override defaults', () => { + const choices = JSON.stringify({ + mode: 'yolo', + granularity: 'coarse', + parallelization: false, + commit_docs: false, + model_profile: 'quality', + workflow: { research: false, plan_check: false, verifier: true, nyquist_validation: false }, + }); + const result = runGsdTools(['config-new-project', choices], tmpDir); + assert.ok(result.success, `Command failed: ${result.error}`); + + const config = readConfig(tmpDir); + assert.strictEqual(config.mode, 'yolo'); + assert.strictEqual(config.granularity, 'coarse'); + assert.strictEqual(config.parallelization, false); + assert.strictEqual(config.commit_docs, false); + assert.strictEqual(config.model_profile, 'quality'); + assert.strictEqual(config.workflow.research, false); + assert.strictEqual(config.workflow.plan_check, false); + assert.strictEqual(config.workflow.verifier, true); + assert.strictEqual(config.workflow.nyquist_validation, false); + // 선택하지 않은 키에 대해서도 기본값이 존재해야 함 + assert.strictEqual(config.git.branching_strategy, 'none'); + assert.strictEqual(typeof config.search_gitignored, 'boolean'); + }); + + test('works with empty choices — all defaults materialized', () => { + const result = runGsdTools(['config-new-project', '{}'], tmpDir); + assert.ok(result.success, `Command failed: ${result.error}`); + + const config = readConfig(tmpDir); + assert.strictEqual(config.model_profile, 'balanced'); + assert.strictEqual(config.commit_docs, true); + assert.strictEqual(config.parallelization, true); + assert.strictEqual(config.search_gitignored, false); + assert.ok(config.git && typeof config.git === 'object'); + assert.strictEqual(config.git.branching_strategy, 'none'); + assert.ok(config.workflow && typeof config.workflow === 'object'); + assert.strictEqual(config.workflow.nyquist_validation, true); + }); + + test('is idempotent — returns already_exists if config exists', () => { + // 첫 번째 호출: 생성 + const choices = JSON.stringify({ mode: 'yolo', granularity: 'fine' }); + const first = runGsdTools(['config-new-project', choices], tmpDir); + assert.ok(first.success, `First call failed: ${first.error}`); + const firstOut = JSON.parse(first.output); + assert.strictEqual(firstOut.created, true); + + // 두 번째 호출: 멱등성 + const second = runGsdTools(['config-new-project', choices], tmpDir); + assert.ok(second.success, `Second call failed: ${second.error}`); + const secondOut = JSON.parse(second.output); + assert.strictEqual(secondOut.created, false); + assert.strictEqual(secondOut.reason, 'already_exists'); + + // config 변경되지 않음 + const config = readConfig(tmpDir); + assert.strictEqual(config.mode, 'yolo'); + assert.strictEqual(config.granularity, 'fine'); + }); + + test('auto_advance in workflow choices is preserved', () => { + const choices = JSON.stringify({ + mode: 'yolo', + granularity: 'standard', + workflow: { research: true, plan_check: true, verifier: true, nyquist_validation: true, auto_advance: true }, + }); + const result = runGsdTools(['config-new-project', choices], tmpDir); + assert.ok(result.success, `Command failed: ${result.error}`); + + const config = readConfig(tmpDir); + assert.strictEqual(config.workflow.auto_advance, true); + }); + + test('rejects invalid JSON choices', () => { + const result = runGsdTools(['config-new-project', '{not-json}'], tmpDir); + assert.strictEqual(result.success, false); + assert.ok(result.error.includes('Invalid JSON'), `Expected "Invalid JSON" in: ${result.error}`); + }); + + test('output JSON has created:true on success', () => { + const choices = JSON.stringify({ mode: 'interactive', granularity: 'standard' }); + const result = runGsdTools(['config-new-project', choices], tmpDir); + assert.ok(result.success, `Command failed: ${result.error}`); + const out = JSON.parse(result.output); + assert.strictEqual(out.created, true); + assert.strictEqual(out.path, '.planning/config.json'); + }); +}); +``` + +- [ ] **Step 1.2: 실패하는 테스트 실행하여 실패 확인** + +```bash +cd /Users/diego/Dev/get-shit-done +node --test tests/config.test.cjs 2>&1 | grep -E "config-new-project|FAIL|Error" +``` + +예상 결과: 모든 `config-new-project` 테스트가 "config-new-project is not a valid command" 또는 유사한 오류로 실패합니다. + +- [ ] **Step 1.3: config.cjs에 `buildNewProjectConfig`와 `cmdConfigNewProject` 구현** + +`get-shit-done/bin/lib/config.cjs`에서 `validateKnownConfigKeyPath` 함수 뒤(약 35번째 줄)와 `ensureConfigFile` 앞에 다음을 추가하세요: + +```js +/** + * 새 프로젝트의 완전히 구체화된 config를 빌드합니다. + * + * 다음 우선순위 순서로 병합합니다: + * 1. 하드코딩된 기본값 + * 2. ~/.gsd/defaults.json의 사용자 수준 기본값(있는 경우) + * 3. userChoices (new-project 중 사용자가 명시적으로 선택한 설정) + * + * 일반 객체를 반환합니다 — 파일을 직접 작성하지 않습니다. + */ +function buildNewProjectConfig(cwd, userChoices) { + const choices = userChoices || {}; + const homedir = require('os').homedir(); + + // Brave Search API 키 가용성 감지 + const braveKeyFile = path.join(homedir, '.gsd', 'brave_api_key'); + const hasBraveSearch = !!(process.env.BRAVE_API_KEY || fs.existsSync(braveKeyFile)); + + // 사용 가능한 경우 ~/.gsd/defaults.json에서 사용자 수준 기본값 로드 + const globalDefaultsPath = path.join(homedir, '.gsd', 'defaults.json'); + let userDefaults = {}; + try { + if (fs.existsSync(globalDefaultsPath)) { + userDefaults = JSON.parse(fs.readFileSync(globalDefaultsPath, 'utf-8')); + // 더 이상 사용되지 않는 "depth" 키를 "granularity"로 마이그레이션 + if ('depth' in userDefaults && !('granularity' in userDefaults)) { + const depthToGranularity = { quick: 'coarse', standard: 'standard', comprehensive: 'fine' }; + userDefaults.granularity = depthToGranularity[userDefaults.depth] || userDefaults.depth; + delete userDefaults.depth; + try { + fs.writeFileSync(globalDefaultsPath, JSON.stringify(userDefaults, null, 2), 'utf-8'); + } catch {} + } + } + } catch { + // 잘못된 전역 기본값 무시 + } + + const hardcoded = { + model_profile: 'balanced', + commit_docs: true, + parallelization: true, + search_gitignored: false, + brave_search: hasBraveSearch, + git: { + branching_strategy: 'none', + phase_branch_template: 'gsd/phase-{phase}-{slug}', + milestone_branch_template: 'gsd/{milestone}-{slug}', + }, + workflow: { + research: true, + plan_check: true, + verifier: true, + nyquist_validation: true, + }, + }; + + // 세 단계 병합: hardcoded <- userDefaults <- choices + return { + ...hardcoded, + ...userDefaults, + ...choices, + git: { + ...hardcoded.git, + ...(userDefaults.git || {}), + ...(choices.git || {}), + }, + workflow: { + ...hardcoded.workflow, + ...(userDefaults.workflow || {}), + ...(choices.workflow || {}), + }, + }; +} + +/** + * 명령어: 새 프로젝트를 위한 완전히 구체화된 .planning/config.json을 생성합니다. + * + * 사용자가 선택한 설정을 JSON 문자열로 받습니다(/gsd-new-project 중 명시적으로 + * 구성한 키들). 나머지 키들은 하드코딩된 기본값과 선택적 ~/.gsd/defaults.json에서 채워집니다. + * + * 멱등성: config.json이 이미 존재하면 { created: false }를 반환합니다. + */ +function cmdConfigNewProject(cwd, choicesJson, raw) { + const configPath = path.join(cwd, '.planning', 'config.json'); + const planningDir = path.join(cwd, '.planning'); + + // 멱등성: 기존 config를 덮어쓰지 않음 + if (fs.existsSync(configPath)) { + output({ created: false, reason: 'already_exists' }, raw, 'exists'); + return; + } + + // 사용자 선택값 파싱 + let userChoices = {}; + if (choicesJson && choicesJson.trim() !== '') { + try { + userChoices = JSON.parse(choicesJson); + } catch (err) { + error('Invalid JSON for config-new-project: ' + err.message); + } + } + + // .planning 디렉토리가 존재하는지 확인 + try { + if (!fs.existsSync(planningDir)) { + fs.mkdirSync(planningDir, { recursive: true }); + } + } catch (err) { + error('Failed to create .planning directory: ' + err.message); + } + + const config = buildNewProjectConfig(cwd, userChoices); + + try { + fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8'); + output({ created: true, path: '.planning/config.json' }, raw, 'created'); + } catch (err) { + error('Failed to write config.json: ' + err.message); + } +} +``` + +`config.cjs` 하단의 `module.exports`에 `cmdConfigNewProject`도 추가하세요. + +- [ ] **Step 1.4: 테스트 실행하여 통과 확인** + +```bash +cd /Users/diego/Dev/get-shit-done +node --test tests/config.test.cjs 2>&1 | tail -20 +``` + +예상 결과: 모든 `config-new-project` 테스트가 통과합니다. 기존 테스트도 계속 통과합니다. + +- [ ] **Step 1.5: 커밋** + +```bash +cd /Users/diego/Dev/get-shit-done +git add get-shit-done/bin/lib/config.cjs tests/config.test.cjs +git commit -m "feat: add config-new-project command for full config materialization" +``` + +--- + +## 작업 2: gsd-tools.cjs에 `config-new-project` 등록 + +**파일.** + +- 수정: `get-shit-done/bin/gsd-tools.cjs` + +- [ ] **Step 2.1: gsd-tools.cjs의 switch에 case 추가** + +`config-get` case 뒤(약 401번째 줄)에 다음을 추가하세요: + +```js + case 'config-new-project': { + config.cmdConfigNewProject(cwd, args[1], raw); + break; + } +``` + +178번째 줄의 usage 문자열도 `config-new-project`를 포함하도록 업데이트하세요: + +현재: `...config-ensure-section, init` +변경: `...config-ensure-section, config-new-project, init` + +- [ ] **Step 2.2: CLI 등록 스모크 테스트** + +```bash +cd /Users/diego/Dev/get-shit-done +node get-shit-done/bin/gsd-tools.cjs config-new-project '{"mode":"interactive","granularity":"standard"}' --cwd /tmp/gsd-smoke-$(date +%s) +``` + +예상 결과: `{"created":true,"path":".planning/config.json"}` (또는 유사한 형태)가 출력됩니다. + +정리: `rm -rf /tmp/gsd-smoke-*` + +- [ ] **Step 2.3: 전체 테스트 스위트 실행** + +```bash +cd /Users/diego/Dev/get-shit-done +node --test tests/config.test.cjs 2>&1 | tail -10 +``` + +예상 결과: 모두 통과합니다. + +- [ ] **Step 2.4: 커밋** + +```bash +cd /Users/diego/Dev/get-shit-done +git add get-shit-done/bin/gsd-tools.cjs +git commit -m "feat: register config-new-project in gsd-tools CLI router" +``` + +--- + +## 작업 3: config-new-project를 사용하도록 new-project.md 워크플로우 업데이트 + +**파일.** + +- 수정: `get-shit-done/workflows/new-project.md` + +이것이 핵심 변경사항입니다. 두 곳을 업데이트해야 합니다: + +- **Step 2a** (auto 모드 config 생성, 약 168–195번째 줄) +- **Step 5** (대화형 모드 config 생성, 약 470–498번째 줄) + +- [ ] **Step 3.1: Step 2a(auto 모드) 업데이트** + +Step 2a에서 config.json을 생성하는 블록을 찾으세요: + +```markdown +Create `.planning/config.json` with mode set to "yolo": + +```json +{ + "mode": "yolo", + "granularity": "[selected]", + ... +} +``` + +``` + +인라인 JSON 작성 지침을 다음으로 교체하세요: + +```markdown +Create `.planning/config.json` using the CLI (fills in all defaults automatically): + +```bash +mkdir -p .planning +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-new-project "$(cat <<'CHOICES' +{ + "mode": "yolo", + "granularity": "[selected: coarse|standard|fine]", + "parallelization": [true|false], + "commit_docs": [true|false], + "model_profile": "[selected: simple|smart|genius|inherit]", + "workflow": { + "research": [true|false], + "plan_check": [true|false], + "verifier": [true|false], + "nyquist_validation": [true|false], + "auto_advance": true + } +} +CHOICES +)" +``` + +The command merges your selections with all runtime defaults (`search_gitignored`, `brave_search`, `git` section), producing a fully-materialized config. + +``` + +- [ ] **Step 3.2: Step 5(대화형 모드) 업데이트** + +Step 5에서 config.json을 생성하는 블록을 찾으세요: + +```markdown +Create `.planning/config.json` with all settings: + +```json +{ + "mode": "yolo|interactive", + ... +} +``` + +``` + +다음으로 교체하세요: + +```markdown +Create `.planning/config.json` using the CLI (fills in all defaults automatically): + +```bash +mkdir -p .planning +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-new-project "$(cat <<'CHOICES' +{ + "mode": "[selected: yolo|interactive]", + "granularity": "[selected: coarse|standard|fine]", + "parallelization": [true|false], + "commit_docs": [true|false], + "model_profile": "[selected: simple|smart|genius|inherit]", + "workflow": { + "research": [true|false], + "plan_check": [true|false], + "verifier": [true|false], + "nyquist_validation": [true|false] + } +} +CHOICES +)" +``` + +The command merges your selections with all runtime defaults (`search_gitignored`, `brave_search`, `git` section), producing a fully-materialized config. + +``` + +- [ ] **Step 3.3: 워크플로우 파일이 올바르게 읽히는지 확인** + +```bash +cd /Users/diego/Dev/get-shit-done +grep -n "config-new-project\|config\.json\|CHOICES" get-shit-done/workflows/new-project.md +``` + +예상 결과: `config-new-project` 2회 등장(단계당 하나씩), config 생성을 위한 인라인 JSON 템플릿 없음. + +- [ ] **Step 3.4: 커밋** + +```bash +cd /Users/diego/Dev/get-shit-done +git add get-shit-done/workflows/new-project.md +git commit -m "feat: use config-new-project in new-project workflow for full config materialization" +``` + +--- + +## 작업 4: 검증 + +- [ ] **Step 4.1: 전체 테스트 스위트 실행** + +```bash +cd /Users/diego/Dev/get-shit-done +node --test tests/ 2>&1 | tail -30 +``` + +예상 결과: 모든 테스트가 통과합니다(회귀 없음). + +- [ ] **Step 4.2: 수동 엔드투엔드 검증** + +`new-project.md`가 새 프로젝트에서 수행하는 작업을 시뮬레이션합니다: + +```bash +# 새로운 프로젝트 디렉토리 생성 +TMP=$(mktemp -d) +cd "$TMP" + +# Step 1 시뮬레이션: init new-project가 반환하는 내용 +node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs init new-project --cwd "$TMP" + +# Step 5 시뮬레이션: 전체 config 생성 +node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs config-new-project '{ + "mode": "interactive", + "granularity": "standard", + "parallelization": true, + "commit_docs": true, + "model_profile": "balanced", + "workflow": { + "research": true, + "plan_check": true, + "verifier": true, + "nyquist_validation": true + } +}' --cwd "$TMP" + +# 파일에 예상되는 12개 키가 모두 있는지 확인 +echo "=== Generated config.json ===" +cat "$TMP/.planning/config.json" + +# 정리 +rm -rf "$TMP" +``` + +예상 출력: `mode`, `granularity`, `model_profile`, `commit_docs`, `parallelization`, `search_gitignored`, `brave_search`, `git`(3개 하위 키), `workflow`(4개 하위 키)가 있는 config.json — 총 12개 최상위 키(또는 `git`과 `workflow`를 단일 키로 계산하면 10개). + +- [ ] **Step 4.3: 멱등성 확인** + +```bash +TMP=$(mktemp -d) +CHOICES='{"mode":"yolo","granularity":"coarse"}' + +node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs config-new-project "$CHOICES" --cwd "$TMP" +FIRST=$(cat "$TMP/.planning/config.json") + +# 두 번째 호출은 no-op이어야 함 +node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs config-new-project "$CHOICES" --cwd "$TMP" +SECOND=$(cat "$TMP/.planning/config.json") + +[ "$FIRST" = "$SECOND" ] && echo "IDEMPOTENT: OK" || echo "IDEMPOTENT: FAIL" +rm -rf "$TMP" +``` + +예상 결과: `IDEMPOTENT: OK` + +- [ ] **Step 4.4: loadConfig가 새 형식을 올바르게 읽는지 확인** + +```bash +TMP=$(mktemp -d) +node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs config-new-project '{ + "mode":"yolo","granularity":"standard","parallelization":true,"commit_docs":true, + "model_profile":"balanced", + "workflow":{"research":true,"plan_check":false,"verifier":true,"nyquist_validation":true} +}' --cwd "$TMP" + +# loadConfig는 plan_check(중첩된 workflow.plan_check로)를 올바르게 읽어야 함 +node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs config-get workflow.plan_check --cwd "$TMP" +# 예상: false + +node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs config-get git.branching_strategy --cwd "$TMP" +# 예상: "none" + +rm -rf "$TMP" +``` + +- [ ] **Step 4.5: 최종 전체 테스트 스위트 + 커밋** + +```bash +cd /Users/diego/Dev/get-shit-done +node --test tests/ 2>&1 | grep -E "pass|fail|error" | tail -5 +``` + +예상 결과: 모두 통과, 0개 실패. + +--- + +## 부록: 업스트림용 PR 설명 + +``` +feat: materialize all config defaults at new-project initialization + +**문제:** +`/gsd-new-project`는 온보딩 중 사용자가 명시적으로 선택한 6개 키만으로 +`.planning/config.json`을 생성합니다. 5개의 추가 키 +(`search_gitignored`, `brave_search`, `git.branching_strategy`, +`git.phase_branch_template`, `git.milestone_branch_template`)는 +런타임에 `loadConfig()`가 자동으로 해석하지만 디스크에는 기록되지 않습니다. + +이로 인해 두 가지 문제가 발생합니다: +1. **발견성**: 소스 코드를 읽지 않고는 `git.branching_strategy`를 + 확인하거나 이해할 수 없습니다 — config에 표시되지 않습니다. +2. **암묵적 확장**: `/gsd-settings` 또는 `config-set`이 처음으로 config에 + 기록할 때도 해당 키들이 추가되지 않습니다. config는 유효한 구성의 + 일부만 반영합니다. + +**해결책:** +`gsd-tools.cjs`에 `config-new-project` CLI 명령어를 추가합니다. 이 명령어는: +- 사용자가 선택한 값을 JSON으로 받습니다. +- 모든 런타임 기본값(환경 감지 `brave_search` 포함)과 병합합니다. +- 완전히 구체화된 config를 한 번에 작성합니다. + +하드코딩된 부분 JSON 템플릿을 작성하는 대신 이 명령어를 호출하도록 +`new-project.md` 워크플로우(Steps 2a와 5)를 업데이트합니다. 기본값은 이제 +정확히 한 곳에 있습니다: `config.cjs`의 `buildNewProjectConfig()`. + +**이 접근이 보수적인 이유:** +- `loadConfig()`, `ensureConfigFile()`, 또는 읽기 경로에는 변경 없음 +- 새로운 config 키 도입 없음 +- 의미적 변경 없음 — 시스템이 이미 자동으로 해석하던 동일한 값들 +- 완전한 하위 호환성: `loadConfig()`는 이전 부분 형식(기존 프로젝트)과 + 새로운 전체 형식을 모두 계속 처리합니다. +- 멱등성: `config-new-project`를 두 번 호출해도 안전합니다. +- 새로운 사용자 대면 플래그 없음 + +**이것이 발견성을 개선하는 이유:** +처음으로 `.planning/config.json`을 여는 개발자는 이제 +`git.branching_strategy: "none"`을 확인하고 GSD 소스를 읽지 않고도 +브랜칭이 가능하고 구성 가능하다는 것을 즉시 이해할 수 있습니다. +``` diff --git a/gsd-opencode/docs/ko-KR/superpowers/specs/2026-03-20-multi-project-workspaces-design.md b/gsd-opencode/docs/ko-KR/superpowers/specs/2026-03-20-multi-project-workspaces-design.md new file mode 100644 index 0000000..6b42f8d --- /dev/null +++ b/gsd-opencode/docs/ko-KR/superpowers/specs/2026-03-20-multi-project-workspaces-design.md @@ -0,0 +1,185 @@ +# 멀티 프로젝트 워크스페이스 (`/gsd-new-workspace`) + +**Issue:** #1241 +**Date:** 2026-03-20 +**Status:** Approved + +## 문제 + +GSD는 작업 디렉토리당 하나의 `.planning/` 디렉토리에 종속되어 있습니다. 20개 이상의 하위 저장소가 있는 모노저장소 스타일 설정에서 여러 독립 프로젝트를 사용하는 사용자나 동일한 저장소에서 피처 브랜치 격리가 필요한 사용자는 수동 클론 및 상태 관리 없이 병렬 GSD 세션을 실행할 수 없습니다. + +## 해결책 + +**물리적 워크스페이스 디렉토리**를 생성, 나열, 제거하는 세 가지 새로운 명령어입니다 — 각각은 저장소 복사본(git worktree 또는 클론)과 독립적인 `.planning/` 디렉토리를 포함합니다. + +이것은 두 가지 사용 사례를 다룹니다: +- **멀티 저장소 오케스트레이션(A):** 상위 디렉토리에서 여러 저장소에 걸친 워크스페이스 +- **피처 브랜치 격리(B):** 현재 저장소의 worktree를 포함하는 워크스페이스(`--repos .`인 경우 A의 특수 케이스) + +## 명령어 + +### `/gsd-new-workspace` + +저장소 복사본과 자체 `.planning/`이 있는 워크스페이스 디렉토리를 생성합니다. + +``` +/gsd-new-workspace --name feature-b --repos hr-ui,ZeymoAPI --path ~/workspaces/feature-b +/gsd-new-workspace --name feature-b --repos . --strategy worktree # 동일 저장소 격리 +``` + +**인수.** + +| 플래그 | 필수 여부 | 기본값 | 설명 | +|------|----------|---------|-------------| +| `--name` | 예 | — | 워크스페이스 이름 | +| `--repos` | 아니오 | 대화형 선택 | 쉼표로 구분된 저장소 경로 또는 이름 | +| `--path` | 아니오 | `~/gsd-workspaces/` | 대상 디렉토리 | +| `--strategy` | 아니오 | `worktree` | `worktree`(가볍고 .git 공유) 또는 `clone`(완전히 독립) | +| `--branch` | 아니오 | `workspace/` | 체크아웃할 브랜치 | +| `--auto` | 아니오 | false | 대화형 질문 건너뛰고 기본값 사용 | + +### `/gsd-list-workspaces` + +워크스페이스 매니페스트를 위해 `~/gsd-workspaces/*/WORKSPACE.md`를 스캔합니다. 이름, 경로, 저장소 수, GSD 상태(PROJECT.md 존재 여부, 현재 페이즈)가 있는 표를 표시합니다. + +### `/gsd-remove-workspace` + +확인 후 워크스페이스 디렉토리를 제거합니다. worktree 전략의 경우 먼저 각 멤버 저장소에 대해 `git worktree remove`를 실행합니다. 저장소에 커밋되지 않은 변경사항이 있으면 거부합니다. + +## 디렉토리 구조 + +``` +~/gsd-workspaces/feature-b/ # 워크스페이스 루트 +├── WORKSPACE.md # 매니페스트 +├── .planning/ # 독립적인 GSD 계획 디렉토리 +│ ├── PROJECT.md # (사용자가 /gsd-new-project를 실행한 경우) +│ ├── STATE.md +│ └── config.json +├── hr-ui/ # 소스 저장소의 git worktree +│ └── (workspace/feature-b 브랜치의 저장소 내용) +└── ZeymoAPI/ # 소스 저장소의 git worktree + └── (workspace/feature-b 브랜치의 저장소 내용) +``` + +주요 속성. +- `.planning/`은 개별 저장소 내부가 아닌 워크스페이스 루트에 있습니다. +- 각 저장소는 워크스페이스 루트 아래의 피어 디렉토리입니다. +- `WORKSPACE.md`는 루트에 있는 유일한 GSD 전용 파일입니다(`.planning/` 외). +- `--strategy clone`의 경우 동일한 구조이지만 저장소는 전체 클론입니다. + +## WORKSPACE.md 형식 + +```markdown +# Workspace: feature-b + +Created: 2026-03-20 +Strategy: worktree + +## Member Repos + +| Repo | Source | Branch | Strategy | +|------|--------|--------|----------| +| hr-ui | /root/source/repos/hr-ui | workspace/feature-b | worktree | +| ZeymoAPI | /root/source/repos/ZeymoAPI | workspace/feature-b | worktree | + +## Notes + +[사용자가 이 워크스페이스의 목적에 대한 컨텍스트를 추가할 수 있습니다] +``` + +## 워크플로우 + +### `/gsd-new-workspace` 워크플로우 단계 + +1. **설정** — `init new-workspace` 호출, JSON 컨텍스트 파싱 +2. **입력 수집** — `--name`/`--repos`/`--path`가 제공되지 않으면 대화형으로 질문합니다. 저장소의 경우 cwd의 하위 `.git` 디렉토리를 옵션으로 표시합니다. +3. **유효성 검사** — 대상 경로가 존재하지 않거나 비어 있음. 소스 저장소가 존재하고 git 저장소임. +4. **워크스페이스 디렉토리 생성** — `mkdir -p ` +5. **저장소 복사** — 각 저장소에 대해. + - Worktree: `git worktree add / -b workspace/` + - Clone: `git clone /` +6. **WORKSPACE.md 작성** — 소스 경로, 전략, 브랜치가 있는 매니페스트 +7. **.planning/ 초기화** — `mkdir -p /.planning` +8. **/gsd-new-project 제안** — 새 워크스페이스에서 프로젝트 초기화를 실행할지 사용자에게 질문 +9. **커밋** — commit_docs가 활성화된 경우 WORKSPACE.md의 원자적 커밋 +10. **완료** — 워크스페이스 경로와 다음 단계 출력 + +### Init 함수(`cmdInitNewWorkspace`) + +다음을 감지합니다. +- cwd의 하위 git 저장소(대화형 저장소 선택을 위해) +- 대상 경로가 이미 존재하는지 여부 +- 소스 저장소에 커밋되지 않은 변경사항이 있는지 여부 +- `git worktree`를 사용할 수 있는지 여부 +- 기본 워크스페이스 기본 디렉토리(`~/gsd-workspaces/`) + +워크플로우 게이팅을 위한 플래그가 포함된 JSON을 반환합니다. + +## 오류 처리 + +### 유효성 검사 오류(생성 차단) + +- **대상 경로가 존재하고 비어 있지 않음** — 다른 이름/경로 선택 제안과 함께 오류 +- **소스 저장소 경로가 존재하지 않거나 git 저장소가 아님** — 실패한 저장소를 나열하는 오류 +- **`git worktree add` 실패**(예: 브랜치가 이미 존재) — `workspace/-` 브랜치로 폴백, 그것도 실패하면 오류 + +### 정상적인 처리 + +- **소스 저장소에 커밋되지 않은 변경사항** — 경고하되 허용(worktree는 브랜치를 새로 체크아웃하며 작업 디렉토리 상태를 복사하지 않음) +- **멀티 저장소 워크스페이스에서 부분 실패** — 성공한 저장소로 워크스페이스를 생성하고 실패를 보고하며 부분적인 WORKSPACE.md 작성 +- **`--repos .`(현재 저장소, 케이스 B)** — 디렉토리 이름 또는 git remote에서 저장소 이름 감지, 하위 디렉토리 이름으로 사용 + +### Remove-Workspace 안전성 + +- **워크스페이스 저장소에 커밋되지 않은 변경사항** — 제거를 거부하고 변경사항이 있는 저장소 출력 +- **Worktree 제거 실패**(예: 소스 저장소가 삭제됨) — 경고하고 디렉토리 정리를 계속 진행 +- **확인** — 워크스페이스 이름을 직접 입력하는 명시적 확인 필요 + +### List-Workspaces 엣지 케이스 + +- **`~/gsd-workspaces/`가 존재하지 않음** — "No workspaces found" +- **WORKSPACE.md는 있지만 내부 저장소가 사라짐** — 워크스페이스를 표시하되 저장소를 누락으로 표시 + +## 테스팅 + +### 단위 테스트(`tests/workspace.test.cjs`) + +1. `cmdInitNewWorkspace`가 올바른 JSON 반환 — 하위 git 저장소 감지, 대상 경로 유효성 검사, git worktree 가용성 감지 +2. WORKSPACE.md 생성 — 저장소 표, 전략, 날짜가 있는 올바른 형식 +3. 저장소 발견 — cwd 하위 항목에서 `.git` 디렉토리 식별, git 디렉토리가 아닌 디렉토리와 파일 건너뜀 +4. 유효성 검사 — 비어 있지 않은 기존 대상 경로 거부, git이 아닌 소스 경로 거부 + +### 통합 테스트(동일 파일) + +5. Worktree 생성 — 워크스페이스 생성, 저장소 디렉토리가 유효한 git worktree인지 확인 +6. Clone 생성 — 워크스페이스 생성, 저장소가 독립적인 클론인지 확인 +7. 워크스페이스 나열 — 두 개의 워크스페이스 생성, 나열 출력에 둘 다 포함되는지 확인 +8. 워크스페이스 제거 — worktree로 워크스페이스 생성, 제거, 정리 확인 +9. 부분 실패 — 유효한 저장소 하나 + 유효하지 않은 경로 하나, 유효한 저장소만으로 워크스페이스 생성 + +모든 테스트는 임시 디렉토리를 사용하고 완료 후 정리합니다. 기존 `node:test` + `node:assert` 패턴을 따릅니다. + +## 구현 파일 + +| 컴포넌트 | 경로 | +|-----------|------| +| 명령어: new-workspace | `commands/gsd/new-workspace.md` | +| 명령어: list-workspaces | `commands/gsd/list-workspaces.md` | +| 명령어: remove-workspace | `commands/gsd/remove-workspace.md` | +| 워크플로우: new-workspace | `get-shit-done/workflows/new-workspace.md` | +| 워크플로우: list-workspaces | `get-shit-done/workflows/list-workspaces.md` | +| 워크플로우: remove-workspace | `get-shit-done/workflows/remove-workspace.md` | +| Init 함수 | `get-shit-done/bin/lib/init.cjs`(`cmdInitNewWorkspace`, `cmdInitListWorkspaces`, `cmdInitRemoveWorkspace` 추가) | +| 라우팅 | `get-shit-done/bin/gsd-tools.cjs`(init switch에 case 추가) | +| 테스트 | `tests/workspace.test.cjs` | + +## 설계 결정 + +| 결정 | 근거 | +|----------|-----------| +| 논리적 레지스트리 대신 물리적 디렉토리 | 파일 시스템이 진실 공급원 — GSD의 기존 cwd 기반 감지 패턴과 일치 | +| 기본 전략으로 Worktree | 가볍고(.git 오브젝트 공유) 생성이 빠르며 정리가 쉬움 | +| 워크스페이스 루트에 `.planning/` | 개별 저장소 계획으로부터 완전한 격리를 제공. 각 워크스페이스는 독립적인 GSD 프로젝트 | +| 중앙 레지스트리 없음 | 상태 드리프트 방지. `list-workspaces`가 파일 시스템을 직접 스캔 | +| A의 특수 케이스로서 케이스 B | `--repos .`는 동일한 메커니즘을 재사용하므로 특별한 피처 브랜치 코드 불필요 | +| 기본 경로 `~/gsd-workspaces/` | `list-workspaces`가 스캔할 예측 가능한 위치, 소스 저장소 외부에 워크스페이스 유지 | diff --git a/gsd-opencode/docs/ko-KR/workflow-discuss-mode.md b/gsd-opencode/docs/ko-KR/workflow-discuss-mode.md new file mode 100644 index 0000000..c79795c --- /dev/null +++ b/gsd-opencode/docs/ko-KR/workflow-discuss-mode.md @@ -0,0 +1,65 @@ +# Discuss 모드: Assumptions vs Interview + +GSD의 discuss 단계는 플래닝 전에 구현 컨텍스트를 수집하는 두 가지 모드를 제공합니다. + +## 모드 + +### `discuss` (기본값) + +기존의 인터뷰 방식 흐름입니다. OpenCode가 단계에서 불명확한 영역을 파악하고 선택지를 제시한 뒤 영역당 약 4개의 질문을 합니다. 다음 상황에 적합합니다. + +- 코드베이스가 새로운 초기 단계 +- 사용자가 사전에 강한 의견을 표현하고 싶은 단계 +- 안내된 대화식 컨텍스트 수집을 선호하는 사용자 + +### `assumptions` + +코드베이스 우선 방식의 흐름입니다. OpenCode가 서브에이전트를 통해 코드베이스를 깊이 분석하고 (관련 파일 5~15개 읽기) 근거가 있는 가정을 도출하여 확인 또는 수정을 위해 제시합니다. 다음 상황에 적합합니다. + +- 명확한 패턴이 있는 기존 코드베이스 +- 인터뷰 질문이 당연하게 느껴지는 사용자 +- 빠른 컨텍스트 수집 (~15~20번 대신 ~2~4번의 상호작용) + +## 설정 + +```bash +# assumptions 모드 활성화 +gsd-tools config-set workflow.discuss_mode assumptions + +# interview 모드로 전환 +gsd-tools config-set workflow.discuss_mode discuss +``` + +설정은 프로젝트별로 적용되며 `.planning/config.json`에 저장됩니다. + +## Assumptions 모드 동작 방식 + +1. **Init** — discuss 모드와 동일 (이전 컨텍스트 로드, 코드베이스 스카우트, todo 확인) +2. **심층 분석** — explore 서브에이전트가 단계와 관련된 코드베이스 파일 5~15개를 읽음 +3. **가정 제시** — 각 가정에는 다음이 포함됩니다. + - OpenCode가 할 작업과 그 이유 (파일 경로 인용) + - 가정이 틀렸을 때 발생하는 문제 + - 신뢰도 수준 (Confident / Likely / Unclear) +4. **확인 또는 수정** — 사용자가 가정을 검토하고 변경이 필요한 항목을 선택 +5. **CONTEXT.md 작성** — discuss 모드와 동일한 출력 형식 + +## 플래그 호환성 + +| 플래그 | `discuss` 모드 | `assumptions` 모드 | +|--------|----------------|-------------------| +| `--auto` | 권장 답변을 자동으로 선택 | 확인 단계를 건너뛰고 Unclear 항목을 자동으로 처리 | +| `--batch` | 질문을 배치로 묶어서 처리 | 해당 없음 (수정 사항이 이미 배치로 처리됨) | +| `--text` | 일반 텍스트 질문 (원격 세션) | 일반 텍스트 질문 (원격 세션) | +| `--analyze` | 질문별 트레이드오프 표 표시 | 해당 없음 (가정에 근거가 포함됨) | + +## 출력 + +두 모드 모두 동일한 6개 섹션을 포함하는 CONTEXT.md를 생성합니다. +- `` — 단계 범위 +- `` — 확정된 구현 결정사항 +- `` — 하위 에이전트가 반드시 읽어야 할 스펙/문서 +- `` — 재사용 가능한 자산, 패턴, 통합 지점 +- `` — 사용자 참고 자료 및 선호사항 +- `` — 향후 단계를 위해 기록된 아이디어 + +하위 에이전트(researcher, planner, checker)는 모드에 관계없이 동일하게 이 파일을 사용합니다. diff --git a/gsd-opencode/docs/pt-BR/AGENTS.md b/gsd-opencode/docs/pt-BR/AGENTS.md new file mode 100644 index 0000000..693ebe8 --- /dev/null +++ b/gsd-opencode/docs/pt-BR/AGENTS.md @@ -0,0 +1,64 @@ +# Referência de Agentes do GSD + +Este documento descreve os papéis dos agentes especializados no ecossistema GSD. +Para a listagem completa com regras detalhadas, consulte [AGENTS.md em inglês](../AGENTS.md). + +--- + +## Visão geral + +O GSD usa um **orquestrador leve** para coordenar subagentes especializados por etapa: + +- pesquisa +- planejamento +- execução +- validação +- depuração + +Cada agente tem responsabilidade clara, entradas/saídas definidas e contexto de trabalho limitado. + +## Famílias de agentes + +### Pesquisa + +- **Project/Phase researchers**: investigam stack, arquitetura, padrões e riscos +- **Research synthesizer**: consolida descobertas em artefatos utilizáveis + +### Planejamento + +- **Planner**: transforma requisitos em planos atômicos +- **Plan checker**: valida consistência, escopo, verificabilidade e dependências + +### Execução + +- **Executor**: implementa tarefas do plano com contexto fresco +- **Integration checker**: verifica se as partes integram corretamente + +### Verificação + +- **Verifier**: compara entrega contra objetivos da fase +- **UAT support**: auxilia no processo de validação manual guiada + +### Diagnóstico + +- **Debugger**: identifica causa-raiz quando há falhas +- **Forensics**: investiga inconsistências de estado/artefatos/histórico + +## Padrões operacionais + +- **Contexto isolado por tarefa**: evita poluição acumulada +- **Commits atômicos**: um commit por unidade de trabalho +- **Execução em ondas**: paralelo quando possível, sequencial quando necessário +- **Loop de revisão**: planejamento e validação iteram até critérios mínimos + +## Boas práticas + +- Prefira tarefas pequenas e verificáveis +- Trave decisões de implementação no `CONTEXT.md` +- Use `assumptions mode` quando já houver padrão consolidado no código +- Ajuste perfil de modelo conforme custo x qualidade + +--- + +> [!NOTE] +> Esta versão em Português é uma referência operacional. Se você estiver contribuindo com o núcleo do framework ou alterando comportamento de agentes, consulte sempre o documento em inglês para detalhes normativos. diff --git a/gsd-opencode/docs/pt-BR/ARCHITECTURE.md b/gsd-opencode/docs/pt-BR/ARCHITECTURE.md new file mode 100644 index 0000000..f60c96c --- /dev/null +++ b/gsd-opencode/docs/pt-BR/ARCHITECTURE.md @@ -0,0 +1,77 @@ +# Arquitetura do GSD + +Visão arquitetural do Get Shit Done (GSD) em Português. +Para detalhes de implementação linha a linha, consulte [ARCHITECTURE.md em inglês](../ARCHITECTURE.md). + +--- + +## Princípios + +- **Orquestração leve** no contexto principal +- **Trabalho pesado em subagentes** +- **Artefatos persistentes** em `.planning/` +- **Validação contínua** por fase +- **Rastreabilidade** por commits atômicos + +## Componentes centrais + +1. **Camada de comando** + Recebe entrada do usuário (`/gsd-*`) e roteia fluxo. + +2. **Camada de orquestração** + Coordena pesquisadores, planejadores, executores e verificadores. + +3. **Camada de artefatos** + Mantém `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, planos e sumários. + +4. **Camada de execução** + Roda tarefas em ondas, respeitando dependências. + +5. **Camada de validação** + Compara entrega contra objetivos, testes e critérios de fase. + +## Fluxo arquitetural (alto nível) + +```text +Entrada (/gsd-comando) + -> Orquestrador + -> Subagentes especializados + -> Artefatos em .planning/ + -> Execução em ondas + -> Verificação/UAT + -> Atualização de estado + commits +``` + +## Estado e persistência + +- `STATE.md`: memória operacional da jornada +- `ROADMAP.md`: visão de progresso por fase +- `SUMMARY.md`: histórico de decisões e resultados por tarefa +- `VALIDATION.md` (quando aplicável): contrato de feedback automatizado + +## Paralelismo + +- Planos independentes: mesma onda (execução paralela) +- Planos dependentes: ondas posteriores (execução sequencial) +- Conflitos de arquivo: serialização controlada + +## Segurança + +- validação de caminhos de arquivo +- detecção de prompt injection +- hooks de guarda para escrita/edição sensível +- scanner CI para padrões de risco + +## Extensibilidade + +GSD suporta evolução por: + +- novos comandos +- novos tipos de agente +- novos artefatos por fase +- novos gates de qualidade/segurança + +--- + +> [!NOTE] +> Esta versão foi criada para consulta de arquitetura em Português. A especificação canônica e completa continua no documento em inglês. diff --git a/gsd-opencode/docs/pt-BR/CLI-TOOLS.md b/gsd-opencode/docs/pt-BR/CLI-TOOLS.md new file mode 100644 index 0000000..764a92e --- /dev/null +++ b/gsd-opencode/docs/pt-BR/CLI-TOOLS.md @@ -0,0 +1,72 @@ +# Referência de Ferramentas CLI + +Resumo em Português das ferramentas CLI do GSD. +Para API completa (assinaturas, argumentos e comportamento detalhado), consulte [CLI-TOOLS.md em inglês](../CLI-TOOLS.md). + +--- + +## Objetivo + +As ferramentas CLI permitem que comandos e agentes do GSD executem ações padronizadas de: + +- leitura e escrita de artefatos +- gerenciamento de fases e roadmap +- execução e validação de planos +- integração com git e automação + +## Áreas funcionais + +### Projeto e estado + +- inicialização de artefatos (`PROJECT`, `REQUIREMENTS`, `ROADMAP`, `STATE`) +- atualização de estado por fase +- controle de milestones + +### Planejamento + +- criação de planos atômicos +- validação pré-execução +- consolidação de pesquisa + +### Execução + +- despacho de tarefas por onda +- persistência de sumários +- checkpoints de progresso + +### Verificação + +- comparação de saída com objetivos +- geração de relatórios de validação +- apoio ao UAT + +### Utilitários + +- leitura/escrita segura de arquivos +- parsing de argumentos +- normalização de paths + +## Boas práticas para autores de agentes + +- Use artefatos existentes como fonte de verdade +- Evite lógica duplicada entre agentes +- Registre saídas em arquivos canônicos de fase +- Garanta que toda tarefa tenha critério claro de done/verify + +--- + +## Fluxo típico (programático) + +```text +Ler contexto do projeto + -> montar input da etapa + -> executar ferramenta CLI + -> persistir artefatos + -> atualizar estado/roadmap + -> retornar resumo para o orquestrador +``` + +--- + +> [!NOTE] +> Este arquivo é um guia prático em Português para quem integra ou estende workflows. Para contratos estritos e detalhes técnicos completos, use o documento original em inglês. diff --git a/gsd-opencode/docs/pt-BR/COMMANDS.md b/gsd-opencode/docs/pt-BR/COMMANDS.md new file mode 100644 index 0000000..f600b91 --- /dev/null +++ b/gsd-opencode/docs/pt-BR/COMMANDS.md @@ -0,0 +1,82 @@ +# Referência de Comandos do GSD + +Este documento descreve os comandos principais do GSD em Português. +Para detalhes completos de flags avançadas e mudanças recentes, consulte também a [versão em inglês](../COMMANDS.md). + +--- + +## Fluxo Principal + +| Comando | Finalidade | Quando usar | +|---------|------------|-------------| +| `/gsd-new-project` | Inicialização completa: perguntas, pesquisa, requisitos e roadmap | Início de projeto | +| `/gsd-discuss-phase [N]` | Captura decisões de implementação | Antes do planejamento | +| `/gsd-ui-phase [N]` | Gera contrato de UI (`UI-SPEC.md`) | Fases com frontend | +| `/gsd-plan-phase [N]` | Pesquisa + planejamento + verificação | Antes de executar uma fase | +| `/gsd-execute-phase ` | Executa planos em ondas paralelas | Após planejamento aprovado | +| `/gsd-verify-work [N]` | UAT manual com diagnóstico automático | Após execução | +| `/gsd-ship [N]` | Cria PR da fase validada | Ao concluir a fase | +| `/gsd-next` | Detecta e executa o próximo passo lógico | Qualquer momento | +| `/gsd-fast ` | Tarefa curta sem planejamento completo | Ajustes triviais | + +## Navegação e Sessão + +| Comando | Finalidade | +|---------|------------| +| `/gsd-progress` | Mostra status atual e próximos passos | +| `/gsd-resume-work` | Retoma contexto da sessão anterior | +| `/gsd-pause-work` | Salva handoff estruturado | +| `/gsd-session-report` | Gera resumo da sessão | +| `/gsd-help` | Lista comandos e uso | +| `/gsd-update` | Atualiza o GSD | + +## Gestão de Fases + +| Comando | Finalidade | +|---------|------------| +| `/gsd-add-phase` | Adiciona fase no roadmap | +| `/gsd-insert-phase [N]` | Insere trabalho urgente entre fases | +| `/gsd-remove-phase [N]` | Remove fase futura e reenumera | +| `/gsd-list-phase-assumptions [N]` | Mostra abordagem assumida pelo OpenCode | +| `/gsd-plan-milestone-gaps` | Cria fases para fechar lacunas de auditoria | + +## Brownfield e Utilidades + +| Comando | Finalidade | +|---------|------------| +| `/gsd-map-codebase` | Mapeia base existente antes de novo projeto | +| `/gsd-quick` | Tarefas ad-hoc com garantias do GSD | +| `/gsd-debug [desc]` | Debug sistemático com estado persistente | +| `/gsd-forensics` | Diagnóstico de falhas no workflow | +| `/gsd-settings` | Configuração de agentes, perfil e toggles | +| `/gsd-set-profile ` | Troca rápida de perfil de modelo | + +## Qualidade de Código + +| Comando | Finalidade | +|---------|------------| +| `/gsd-review` | Peer review com múltiplas IAs | +| `/gsd-pr-branch` | Cria branch limpa sem commits de planejamento | +| `/gsd-audit-uat` | Audita dívida de validação/UAT | + +## Backlog e Threads + +| Comando | Finalidade | +|---------|------------| +| `/gsd-add-backlog ` | Adiciona item no backlog (999.x) | +| `/gsd-review-backlog` | Promove, mantém ou remove itens | +| `/gsd-plant-seed ` | Registra ideia com gatilho futuro | +| `/gsd-thread [nome]` | Gerencia threads persistentes | + +--- + +## Exemplo rápido + +```bash +/gsd-new-project +/gsd-discuss-phase 1 +/gsd-plan-phase 1 +/gsd-execute-phase 1 +/gsd-verify-work 1 +/gsd-ship 1 +``` diff --git a/gsd-opencode/docs/pt-BR/CONFIGURATION.md b/gsd-opencode/docs/pt-BR/CONFIGURATION.md new file mode 100644 index 0000000..a50c091 --- /dev/null +++ b/gsd-opencode/docs/pt-BR/CONFIGURATION.md @@ -0,0 +1,84 @@ +# Referência de Configuração do GSD + +Configurações do projeto ficam em `.planning/config.json`. +Esta versão resume os parâmetros principais em Português. Para schema completo, veja [inglês](../CONFIGURATION.md). + +--- + +## Estrutura base + +```json +{ + "mode": "interactive", + "granularity": "standard", + "model_profile": "balanced", + "planning": { + "commit_docs": true, + "search_gitignored": false + }, + "workflow": { + "research": true, + "plan_check": true, + "verifier": true, + "nyquist_validation": true, + "ui_phase": true, + "ui_safety_gate": true, + "research_before_questions": false, + "discuss_mode": "standard", + "skip_discuss": false + } +} +``` + +## Configurações principais + +| Chave | Opções | Padrão | Descrição | +|------|--------|--------|-----------| +| `mode` | `interactive`, `yolo` | `interactive` | `yolo` autoaprova; `interactive` confirma cada etapa | +| `granularity` | `coarse`, `standard`, `fine` | `standard` | Granularidade de fases/planos | +| `model_profile` | `quality`, `balanced`, `budget`, `inherit` | `balanced` | Perfil de modelos por agente | + +## Planning + +| Chave | Padrão | Descrição | +|------|--------|-----------| +| `planning.commit_docs` | `true` | Comitar `.planning/` no git | +| `planning.search_gitignored` | `false` | Incluir arquivos ignorados em buscas amplas | + +## Workflow toggles + +| Chave | Padrão | Descrição | +|------|--------|-----------| +| `workflow.research` | `true` | Pesquisa antes de planejar | +| `workflow.plan_check` | `true` | Loop de verificação de plano | +| `workflow.verifier` | `true` | Verificação pós-execução | +| `workflow.nyquist_validation` | `true` | Camada de validação automatizada por requisito | +| `workflow.ui_phase` | `true` | Contrato de UI para fases frontend | +| `workflow.ui_safety_gate` | `true` | Gate de segurança para registry UI | +| `workflow.research_before_questions` | `false` | Pesquisa antes da discussão | +| `workflow.discuss_mode` | `standard` | Discussão aberta; use `assumptions` para modo baseado em código | +| `workflow.skip_discuss` | `false` | Pula discuss-phase no modo autônomo | + +## Git branching + +| Chave | Opções | Padrão | Descrição | +|------|--------|--------|-----------| +| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | Estratégia de criação de branches | +| `git.phase_branch_template` | string | `gsd/phase-{phase}-{slug}` | Nome para branch por fase | +| `git.milestone_branch_template` | string | `gsd/{milestone}-{slug}` | Nome para branch de milestone | +| `git.quick_branch_template` | string ou `null` | `null` | Branch opcional para `/gsd-quick` | + +## Perfis de modelo + +| Perfil | Objetivo | +|--------|----------| +| `quality` | Melhor qualidade, maior custo | +| `balanced` | Equilíbrio (padrão recomendado) | +| `budget` | Menor custo | +| `inherit` | Herdar modelo da sessão/runtime | + +Troca rápida: + +```bash +/gsd-set-profile budget +``` diff --git a/gsd-opencode/docs/pt-BR/FEATURES.md b/gsd-opencode/docs/pt-BR/FEATURES.md new file mode 100644 index 0000000..c2c4f52 --- /dev/null +++ b/gsd-opencode/docs/pt-BR/FEATURES.md @@ -0,0 +1,56 @@ +# Referência de Recursos do GSD + +Visão em Português dos recursos centrais do GSD. +Para catálogo completo e detalhamento exaustivo, consulte [FEATURES.md em inglês](../FEATURES.md). + +--- + +## Recursos principais + +- **Desenvolvimento orientado por fases** com artefatos de planejamento versionados +- **Engenharia de contexto** para reduzir degradação de qualidade em sessões longas +- **Planejamento em tarefas atômicas** para execução mais previsível +- **Execução em ondas paralelas** com controle por dependências +- **Commits atômicos por tarefa** para rastreabilidade e rollback +- **Verificação pós-execução** com foco em objetivos da fase +- **UAT guiado** via `/gsd-verify-work` +- **Suporte brownfield** com `/gsd-map-codebase` +- **Workstreams** para trilhas paralelas sem colisão de estado +- **Backlog, seeds e threads** para memória de médio/longo prazo + +## Qualidade e segurança + +- **Plan-check** antes de executar +- **Nyquist validation** para mapear requisito -> validação automatizada +- **Detecção de prompt injection** em entradas do usuário +- **Prevenção de path traversal** em caminhos fornecidos +- **Hooks de proteção** para alterações fora de contexto de workflow + +## UX de frontend + +- **`/gsd-ui-phase`**: contrato visual antes da execução +- **`/gsd-ui-review`**: auditoria visual em 6 pilares +- **UI safety gate** para uso de registries de terceiros + +## Operação e manutenção + +- **Perfis de modelo** (`quality`, `balanced`, `budget`, `inherit`) +- **Ajuste por toggles** para custo/qualidade/velocidade +- **Diagnóstico forense** com `/gsd-forensics` +- **Relatório de sessão** com `/gsd-session-report` + +--- + +## Atalhos recomendados por cenário + +| Cenário | Comandos | +|--------|----------| +| Projeto novo | `/gsd-new-project` -> `/gsd-discuss-phase` -> `/gsd-plan-phase` -> `/gsd-execute-phase` | +| Correção rápida | `/gsd-quick` | +| Código existente | `/gsd-map-codebase` -> `/gsd-new-project` | +| Fechamento de release | `/gsd-audit-milestone` -> `/gsd-complete-milestone` | + +--- + +> [!NOTE] +> Este arquivo é uma versão de referência rápida em Português para facilitar uso diário. Para detalhes de baixo nível, requisitos formais e comportamento completo de cada recurso, use o documento original em inglês. diff --git a/gsd-opencode/docs/pt-BR/README.md b/gsd-opencode/docs/pt-BR/README.md new file mode 100644 index 0000000..d6d66e2 --- /dev/null +++ b/gsd-opencode/docs/pt-BR/README.md @@ -0,0 +1,30 @@ +# Documentação do GSD + +Documentação abrangente do framework Get Shit Done (GSD) — um sistema de meta-prompting, engenharia de contexto e desenvolvimento orientado por especificações para agentes de IA. + +## Índice da documentação + +| Documento | Público | Descrição | +|----------|----------|-------------| +| [Guia do Usuário](USER-GUIDE.md) | Todos os usuários | Fluxos de trabalho, troubleshooting e recuperação | +| [Arquitetura](ARCHITECTURE.md) | Contribuidores, usuários avançados | Arquitetura do sistema, modelo de agentes e design interno | +| [Referência de comandos](COMMANDS.md) | Todos os usuários | Comandos, sintaxe, flags, opções e exemplos | +| [Referência de configuração](CONFIGURATION.md) | Todos os usuários | Schema completo de configuração, toggles e perfis | +| [Referência de recursos](FEATURES.md) | Todos os usuários | Recursos e requisitos detalhados | +| [Referência de agentes](AGENTS.md) | Contribuidores, usuários avançados | Agentes especializados, papéis e padrões de orquestração | +| [Ferramentas CLI](CLI-TOOLS.md) | Contribuidores, autores de agentes | API programática `gsd-tools.cjs` | +| [Monitor de contexto](context-monitor.md) | Todos os usuários | Arquitetura de monitoramento da janela de contexto | +| [Discuss Mode](workflow-discuss-mode.md) | Todos os usuários | Modo suposições vs entrevista no `discuss-phase` | +| [Referências](references/) | Todos os usuários | Guias complementares de decisão, verificação e padrões | +| [Superpowers](superpowers/) | Contribuidores | Planos e specs avançadas do projeto | + +## Links rápidos + +- **Começar rápido:** [README principal](../../README.pt-BR.md) -> instalação -> `/gsd-new-project` +- **Fluxo completo:** [Guia do usuário](USER-GUIDE.md) +- **Comandos:** [Referência de comandos](COMMANDS.md) +- **Configuração:** [Referência de configuração](CONFIGURATION.md) +- **Arquitetura interna:** [Arquitetura](ARCHITECTURE.md) + +> [!NOTE] +> Esta pasta `pt-BR` contém a versão em Português dos documentos de uso geral. Documentação técnica avançada ainda referencia os arquivos em inglês para manter precisão e atualização. diff --git a/gsd-opencode/docs/pt-BR/USER-GUIDE.md b/gsd-opencode/docs/pt-BR/USER-GUIDE.md new file mode 100644 index 0000000..a3cc260 --- /dev/null +++ b/gsd-opencode/docs/pt-BR/USER-GUIDE.md @@ -0,0 +1,335 @@ +# Guia do Usuário do GSD + +Referência detalhada de workflows, troubleshooting e configuração. Para setup rápido, veja o [README](../../README.pt-BR.md). + +--- + +## Sumário + +- [Fluxo de trabalho](#fluxo-de-trabalho) +- [Contrato de UI](#contrato-de-ui) +- [Backlog e Threads](#backlog-e-threads) +- [Workstreams](#workstreams) +- [Segurança](#segurança) +- [Referência de comandos](#referência-de-comandos) +- [Configuração](#configuração) +- [Exemplos de uso](#exemplos-de-uso) +- [Troubleshooting](#troubleshooting) +- [Recuperação rápida](#recuperação-rápida) + +--- + +## Fluxo de trabalho + +Fluxo recomendado por fase: + +1. `/gsd-discuss-phase [N]` — trava preferências de implementação +2. `/gsd-ui-phase [N]` — contrato visual para fases frontend +3. `/gsd-plan-phase [N]` — pesquisa + plano + validação +4. `/gsd-execute-phase [N]` — execução em ondas paralelas +5. `/gsd-verify-work [N]` — UAT manual com diagnóstico +6. `/gsd-ship [N]` — cria PR (opcional) + +Para iniciar projeto novo: + +```bash +/gsd-new-project +``` + +Para seguir automaticamente o próximo passo: + +```bash +/gsd-next +``` + +### Nyquist Validation + +Durante `plan-phase`, o GSD pode mapear requisitos para comandos de teste automáticos antes da implementação. Isso gera `{phase}-VALIDATION.md` e aumenta a confiabilidade de verificação pós-execução. + +Desativar: + +```json +{ + "workflow": { + "nyquist_validation": false + } +} +``` + +### Modo de discussão por suposições + +Com `workflow.discuss_mode: "assumptions"`, o GSD analisa o código antes de perguntar, apresenta suposições estruturadas e pede apenas correções. + +--- + +## Contrato de UI + +### Comandos + +| Comando | Descrição | +|---------|-----------| +| `/gsd-ui-phase [N]` | Gera contrato de design `UI-SPEC.md` para a fase | +| `/gsd-ui-review [N]` | Auditoria visual retroativa em 6 pilares | + +### Quando usar + +- Rode `/gsd-ui-phase` depois de `/gsd-discuss-phase` e antes de `/gsd-plan-phase`. +- Rode `/gsd-ui-review` após execução/validação para avaliar qualidade visual e consistência. + +### Configurações relacionadas + +| Setting | Padrão | O que controla | +|---------|--------|----------------| +| `workflow.ui_phase` | `true` | Gera contratos de UI para fases frontend | +| `workflow.ui_safety_gate` | `true` | Ativa gate de segurança para componentes de registry | + +--- + +## Backlog e Threads + +### Backlog (999.x) + +Ideias fora da sequência ativa vão para backlog: + +```bash +/gsd-add-backlog "Camada GraphQL" +/gsd-add-backlog "Responsividade mobile" +``` + +Promover/revisar: + +```bash +/gsd-review-backlog +``` + +### Seeds + +Seeds guardam ideias futuras com condição de gatilho: + +```bash +/gsd-plant-seed "Adicionar colaboração real-time quando infra de WebSocket estiver pronta" +``` + +### Threads persistentes + +Threads são contexto leve entre sessões: + +```bash +/gsd-thread +/gsd-thread fix-deploy-key-auth +/gsd-thread "Investigar timeout TCP" +``` + +--- + +## Workstreams + +Workstreams permitem trabalho paralelo sem colisão de estado de planejamento. + +| Comando | Função | +|---------|--------| +| `/gsd-workstreams create ` | Cria workstream isolado | +| `/gsd-workstreams switch ` | Troca workstream ativo | +| `/gsd-workstreams list` | Lista workstreams | +| `/gsd-workstreams complete ` | Finaliza e arquiva workstream | + +`workstreams` compartilham o mesmo código/git, mas isolam artefatos de `.planning/`. + +--- + +## Segurança + +O GSD aplica defesa em profundidade: + +- prevenção de path traversal em entradas de arquivo +- detecção de prompt injection em texto do usuário +- hooks de proteção para escrita em `.planning/` +- scanner CI para padrões de injeção em agentes/workflows/comandos + +Para arquivos sensíveis, use deny list no OpenCode. + +--- + +## Referência de comandos + +### Fluxo principal + +| Comando | Quando usar | +|---------|-------------| +| `/gsd-new-project` | Início de projeto | +| `/gsd-discuss-phase [N]` | Definir preferências antes do plano | +| `/gsd-plan-phase [N]` | Criar e validar planos | +| `/gsd-execute-phase [N]` | Executar planos em ondas | +| `/gsd-verify-work [N]` | UAT manual | +| `/gsd-ship [N]` | Gerar PR da fase | +| `/gsd-next` | Próximo passo automático | + +### Gestão e utilidades + +| Comando | Quando usar | +|---------|-------------| +| `/gsd-progress` | Ver status atual | +| `/gsd-resume-work` | Retomar sessão | +| `/gsd-pause-work` | Pausar com handoff | +| `/gsd-session-report` | Resumo da sessão | +| `/gsd-quick` | Tarefa ad-hoc com garantias GSD | +| `/gsd-debug [desc]` | Debug sistemático | +| `/gsd-forensics` | Diagnóstico de workflow quebrado | +| `/gsd-settings` | Ajustar workflow/modelos | +| `/gsd-set-profile ` | Troca rápida de perfil | + +Para lista completa e flags avançadas, consulte [Command Reference](../COMMANDS.md). + +--- + +## Configuração + +Arquivo de configuração: `.planning/config.json` + +### Núcleo + +| Setting | Opções | Padrão | +|---------|--------|--------| +| `mode` | `interactive`, `yolo` | `interactive` | +| `granularity` | `coarse`, `standard`, `fine` | `standard` | +| `model_profile` | `quality`, `balanced`, `budget`, `inherit` | `balanced` | + +### Workflow + +| Setting | Padrão | +|---------|--------| +| `workflow.research` | `true` | +| `workflow.plan_check` | `true` | +| `workflow.verifier` | `true` | +| `workflow.nyquist_validation` | `true` | +| `workflow.ui_phase` | `true` | +| `workflow.ui_safety_gate` | `true` | + +### Perfis de modelo + +| Perfil | Uso recomendado | +|--------|------------------| +| `quality` | trabalho crítico, maior qualidade | +| `balanced` | padrão recomendado | +| `budget` | reduzir custo de tokens | +| `inherit` | seguir modelo da sessão/runtime | + +Detalhes completos: [Configuration Reference](../CONFIGURATION.md). + +--- + +## Exemplos de uso + +### Projeto novo + +```bash +OpenCode --dangerously-skip-permissions +/gsd-new-project +/gsd-discuss-phase 1 +/gsd-ui-phase 1 +/gsd-plan-phase 1 +/gsd-execute-phase 1 +/gsd-verify-work 1 +/gsd-ship 1 +``` + +### Código já existente + +```bash +/gsd-map-codebase +/gsd-new-project +``` + +### Correção rápida + +```bash +/gsd-quick +> "Corrigir botão de login no mobile Safari" +``` + +### Preparação para release + +```bash +/gsd-audit-milestone +/gsd-plan-milestone-gaps +/gsd-complete-milestone +``` + +--- + +## Troubleshooting + +### "Project already initialized" + +`.planning/PROJECT.md` já existe. Apague `.planning/` se quiser reiniciar do zero. + +### Sessão longa degradando contexto + +Use `/new` entre etapas grandes e retome com `/gsd-resume-work` ou `/gsd-progress`. + +### Plano desalinhado + +Rode `/gsd-discuss-phase [N]` antes do plano e valide suposições com `/gsd-list-phase-assumptions [N]`. + +### Execução falhou ou saiu com stubs + +Replaneje com escopo menor (tarefas menores por plano). + +### Custo alto + +Use perfil budget: + +```bash +/gsd-set-profile budget +``` + +### Runtime não-OpenCode (Codex/OpenCode/Gemini) + +Use `resolve_model_ids: "omit"` para deixar o runtime resolver modelos padrão. + +--- + +## Recuperação rápida + +| Problema | Solução | +|---------|---------| +| Perdeu contexto | `/gsd-resume-work` ou `/gsd-progress` | +| Fase deu errado | `git revert` + replanejar | +| Precisa alterar escopo | `/gsd-add-phase`, `/gsd-insert-phase`, `/gsd-remove-phase` | +| Bug em workflow | `/gsd-forensics` | +| Correção pontual | `/gsd-quick` | +| Custo alto | `/gsd-set-profile budget` | +| Não sabe próximo passo | `/gsd-next` | + +--- + +## Estrutura de arquivos do projeto + +```text +.planning/ + PROJECT.md + REQUIREMENTS.md + ROADMAP.md + STATE.md + config.json + MILESTONES.md + HANDOFF.json + research/ + reports/ + todos/ + debug/ + codebase/ + phases/ + XX-phase-name/ + XX-YY-PLAN.md + XX-YY-SUMMARY.md + CONTEXT.md + RESEARCH.md + VERIFICATION.md + XX-UI-SPEC.md + XX-UI-REVIEW.md + ui-reviews/ +``` + +> [!NOTE] +> Esta é a versão pt-BR do guia para uso diário. Para detalhes técnicos exatos e cobertura completa de parâmetros avançados, consulte também o [guia original em inglês](../USER-GUIDE.md). diff --git a/gsd-opencode/docs/pt-BR/context-monitor.md b/gsd-opencode/docs/pt-BR/context-monitor.md new file mode 100644 index 0000000..7080d5a --- /dev/null +++ b/gsd-opencode/docs/pt-BR/context-monitor.md @@ -0,0 +1,40 @@ +# Monitor de Contexto + +O monitor de contexto ajuda a evitar degradação de qualidade em sessões longas, alertando sobre uso excessivo da janela de contexto. + +Para detalhes completos de implementação, veja [context-monitor.md em inglês](../context-monitor.md). + +--- + +## Objetivos + +- identificar quando a sessão principal está saturando +- recomendar ações de recuperação (`/new`, `/gsd-resume-work`, `/gsd-progress`) +- manter previsibilidade durante ciclos longos de desenvolvimento + +## Como funciona + +1. coleta sinais de uso da janela de contexto +2. compara com limiares de alerta +3. emite avisos progressivos +4. sugere retomada por artefatos persistentes + +## Estratégia recomendada + +- Limpe contexto entre fases grandes +- Execute tarefas pesadas em subagentes +- Mantenha o estado em `.planning/` como fonte de verdade + +## Recuperação quando há degradação + +```bash +/new +/gsd-resume-work +# ou +/gsd-progress +``` + +--- + +> [!TIP] +> O monitor não substitui boas práticas de escopo. Planos pequenos e verificáveis continuam sendo o principal fator de qualidade. diff --git a/gsd-opencode/docs/pt-BR/superpowers/README.md b/gsd-opencode/docs/pt-BR/superpowers/README.md new file mode 100644 index 0000000..7618b75 --- /dev/null +++ b/gsd-opencode/docs/pt-BR/superpowers/README.md @@ -0,0 +1,11 @@ +# Superpowers (pt-BR) + +Documentos avançados traduzidos: + +## Plans + +- [2026-03-18-materialize-new-project-config](plans/2026-03-18-materialize-new-project-config.md) + +## Specs + +- [2026-03-20-multi-project-workspaces-design](specs/2026-03-20-multi-project-workspaces-design.md) diff --git a/gsd-opencode/docs/pt-BR/superpowers/plans/2026-03-23-materialize-new-project-config.md b/gsd-opencode/docs/pt-BR/superpowers/plans/2026-03-23-materialize-new-project-config.md new file mode 100644 index 0000000..81cf434 --- /dev/null +++ b/gsd-opencode/docs/pt-BR/superpowers/plans/2026-03-23-materialize-new-project-config.md @@ -0,0 +1,60 @@ +# Plano: Materializar Configuração no `new-project` (pt-BR) + +Data original: 2026-03-23 +Fonte canônica: `docs/superpowers/plans/2026-03-18-materialize-new-project-config.md` + +--- + +## Contexto + +Este plano formaliza a materialização explícita da configuração do projeto durante `/gsd-new-project`, garantindo que escolhas feitas na inicialização sejam persistidas de forma determinística em `.planning/config.json`. + +## Objetivos + +- garantir persistência imediata de decisões de setup +- reduzir divergência entre estado interativo e arquivo de configuração +- facilitar retomada de sessão e reprodutibilidade + +## Escopo + +Inclui: + +- mapeamento de respostas de setup para chaves de configuração +- escrita idempotente de `.planning/config.json` +- validação mínima de schema antes de persistir + +Não inclui: + +- redesenho completo do schema +- migração profunda de versões legadas + +## Estratégia de implementação + +1. Capturar decisões de setup em estrutura intermediária +2. Normalizar valores (tipos/enum/padrões) +3. Aplicar merge controlado no config existente +4. Persistir arquivo final e registrar resumo no estado + +## Critérios de aceitação + +- após `/gsd-new-project`, `config.json` reflete as escolhas feitas +- rerun não duplica nem corrompe campos +- comandos subsequentes observam os valores persistidos + +## Riscos e mitigação + +- **Risco:** configuração parcial em caso de falha no meio + **Mitigação:** escrita atômica (arquivo temporário + replace) +- **Risco:** inconsistência com defaults implícitos + **Mitigação:** normalização centralizada com fallback explícito + +## Verificação + +- teste de inicialização limpa +- teste de reexecução com config pré-existente +- teste de compatibilidade com comandos dependentes de config + +--- + +> [!NOTE] +> Esta versão em Português é uma tradução operacional do plano para consulta rápida. O documento original permanece como referência técnica canônica. diff --git a/gsd-opencode/docs/pt-BR/superpowers/specs/2026-03-20-multi-project-workspaces-design.md b/gsd-opencode/docs/pt-BR/superpowers/specs/2026-03-20-multi-project-workspaces-design.md new file mode 100644 index 0000000..815eeb0 --- /dev/null +++ b/gsd-opencode/docs/pt-BR/superpowers/specs/2026-03-20-multi-project-workspaces-design.md @@ -0,0 +1,55 @@ +# Especificação: Design de Multi-Project Workspaces (pt-BR) + +Data original: 2026-03-20 +Fonte canônica: `docs/superpowers/specs/2026-03-20-multi-project-workspaces-design.md` + +--- + +## Problema + +Times e desenvolvedores frequentemente precisam trabalhar em múltiplos repositórios/áreas em paralelo, mantendo isolamento de estado de planejamento sem perder fluidez operacional. + +## Proposta + +Introduzir workspaces multi-projeto com: + +- isolamento de `.planning/` por workspace +- suporte a múltiplos repositórios (worktree/clone) +- comandos para criação, listagem e remoção + +## Objetivos de design + +- isolamento forte de estado +- operação simples via comandos (`new/list/remove workspace`) +- baixo acoplamento com o workflow padrão +- fácil observabilidade do que está ativo + +## Modelo conceitual + +- **Workspace**: unidade isolada de execução GSD +- **Member repos**: repositórios associados ao workspace +- **Manifest**: arquivo de metadados com estrutura e status + +## Fluxo de uso + +1. Criar workspace com nome e repositórios alvo +2. Inicializar/retomar fluxo GSD dentro do workspace +3. Operar fases normalmente com estado isolado +4. Finalizar e remover quando concluído + +## Considerações + +- comandos devem deixar explícito o contexto atual +- limpeza precisa remover artefatos derivados com segurança +- comportamento deve ser previsível em ambientes monorepo + +## Critérios de aceitação + +- workspaces independentes não colidem estado +- listagem mostra workspace ativo e metadados essenciais +- remoção limpa artefatos sem afetar repositórios externos + +--- + +> [!NOTE] +> Esta versão em Português resume a especificação de design para uso prático. O arquivo original em inglês mantém o detalhamento normativo completo. diff --git a/gsd-opencode/docs/pt-BR/workflow-discuss-mode.md b/gsd-opencode/docs/pt-BR/workflow-discuss-mode.md new file mode 100644 index 0000000..ec44c2d --- /dev/null +++ b/gsd-opencode/docs/pt-BR/workflow-discuss-mode.md @@ -0,0 +1,62 @@ +# Discuss Mode (Modo de Discussão) + +O GSD oferece dois estilos para `/gsd-discuss-phase`: + +- **`standard`**: entrevista aberta para levantar preferências +- **`assumptions`**: análise do código primeiro, seguida de confirmação/correção de suposições + +Para referência completa, veja [workflow-discuss-mode.md em inglês](../workflow-discuss-mode.md). + +--- + +## Quando usar `standard` + +Use quando: + +- o projeto ainda não tem padrões claros +- você quer explorar alternativas livremente +- há decisões de produto/UX em aberto + +Vantagem: descoberta ampla. +Trade-off: pode consumir mais tempo de perguntas. + +## Quando usar `assumptions` + +Use quando: + +- o código já tem convenções estáveis +- você quer reduzir fricção no intake +- o time prefere revisão de propostas em vez de entrevista aberta + +Vantagem: velocidade e consistência com o código existente. +Trade-off: depende da qualidade do mapeamento de contexto. + +## Como habilitar + +Via `/gsd-settings`, defina: + +```json +{ + "workflow": { + "discuss_mode": "assumptions" + } +} +``` + +## Fluxo no modo `assumptions` + +1. GSD lê `PROJECT.md`, mapeamento de código e convenções +2. Gera lista estruturada de suposições +3. Você confirma, corrige ou expande +4. GSD escreve `CONTEXT.md` com decisões consolidadas + +## Boas práticas + +- Revise suposições antes do `plan-phase` +- Corrija ambiguidades de nomes/paths cedo +- Se o plano sair desalinhado, volte ao discuss-phase e refine + +--- + +> [!NOTE] +> Para ambientes com múltiplos runtimes e perfis de modelo dinâmicos, prefira `assumptions` quando o reuso de padrões de código for prioridade. diff --git a/gsd-opencode/docs/superpowers/plans/2026-03-18-materialize-new-project-config.md b/gsd-opencode/docs/superpowers/plans/2026-03-18-materialize-new-project-config.md new file mode 100644 index 0000000..ebb76c8 --- /dev/null +++ b/gsd-opencode/docs/superpowers/plans/2026-03-18-materialize-new-project-config.md @@ -0,0 +1,700 @@ +# Materialize new-project config on initialization + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** When `/gsd-new-project` creates `.planning/config.json`, the file contains all effective defaults — not just the 6 user-chosen keys — so developers can see every setting without reading source code. + +**Architecture:** Add a single JS function `buildNewProjectConfig(cwd, userChoices)` in `config.cjs` as the one source of truth for a new project's full config. Expose it as a CLI command `config-new-project`. Update the `new-project.md` workflow to call this command instead of writing a partial JSON inline. + +**Tech Stack:** Node.js/CommonJS, existing gsd-tools CLI, `node:test` for tests. + +--- + +## Background: what exists today + +`new-project.md` Step 5 writes this partial config (the AI fills the template): + +```json +{ + "mode": "...", "granularity": "...", "parallelization": "...", + "commit_docs": "...", "model_profile": "...", + "workflow": { "research", "plan_check", "verifier", "nyquist_validation" } +} +``` + +Missing keys silently resolved by `loadConfig()` at runtime: + +- `search_gitignored: false` +- `brave_search: false` (or env-detected `true`) +- `git.branching_strategy: "none"` +- `git.phase_branch_template: "gsd/phase-{phase}-{slug}"` +- `git.milestone_branch_template: "gsd/{milestone}-{slug}"` + +Full config that should exist from the start: + +```json +{ + "mode": "yolo|interactive", + "granularity": "coarse|standard|fine", + "model_profile": "balanced", + "commit_docs": true, + "parallelization": true, + "search_gitignored": false, + "brave_search": false, + "git": { + "branching_strategy": "none", + "phase_branch_template": "gsd/phase-{phase}-{slug}", + "milestone_branch_template": "gsd/{milestone}-{slug}" + }, + "workflow": { + "research": true, + "plan_check": true, + "verifier": true, + "nyquist_validation": true + } +} +``` + +--- + +## File map + +| File | Action | Purpose | +|------|--------|---------| +| `get-shit-done/bin/lib/config.cjs` | Modify | Add `buildNewProjectConfig()` + `cmdConfigNewProject()` | +| `get-shit-done/bin/gsd-tools.cjs` | Modify | Register `config-new-project` case + update usage string | +| `get-shit-done/workflows/new-project.md` | Modify | Steps 2a + 5: replace inline JSON write with CLI call | +| `tests/config.test.cjs` | Modify | Add `config-new-project` test suite | + +--- + +## task 1: Add `buildNewProjectConfig` and `cmdConfigNewProject` to config.cjs + +**Files:** + +- Modify: `get-shit-done/bin/lib/config.cjs` + +- [ ] **Step 1.1: write the failing tests first** + +Add to `tests/config.test.cjs` (after the `config-get` suite, before `module.exports`): + +```js +// ─── config-new-project ────────────────────────────────────────────────────── + +describe('config-new-project command', () => { + let tmpDir; + + beforeEach(() => { + tmpDir = createTempProject(); + }); + + afterEach(() => { + cleanup(tmpDir); + }); + + test('creates full config with all expected top-level and nested keys', () => { + const choices = JSON.stringify({ + mode: 'interactive', + granularity: 'standard', + parallelization: true, + commit_docs: true, + model_profile: 'balanced', + workflow: { research: true, plan_check: true, verifier: true, nyquist_validation: true }, + }); + const result = runGsdTools(['config-new-project', choices], tmpDir); + assert.ok(result.success, `Command failed: ${result.error}`); + + const config = readConfig(tmpDir); + + // User choices present + assert.strictEqual(config.mode, 'interactive'); + assert.strictEqual(config.granularity, 'standard'); + assert.strictEqual(config.parallelization, true); + assert.strictEqual(config.commit_docs, true); + assert.strictEqual(config.model_profile, 'balanced'); + + // Defaults materialized + assert.strictEqual(typeof config.search_gitignored, 'boolean'); + assert.strictEqual(typeof config.brave_search, 'boolean'); + + // git section present with all three keys + assert.ok(config.git && typeof config.git === 'object', 'git section should exist'); + assert.strictEqual(config.git.branching_strategy, 'none'); + assert.strictEqual(config.git.phase_branch_template, 'gsd/phase-{phase}-{slug}'); + assert.strictEqual(config.git.milestone_branch_template, 'gsd/{milestone}-{slug}'); + + // workflow section present with all four keys + assert.ok(config.workflow && typeof config.workflow === 'object', 'workflow section should exist'); + assert.strictEqual(config.workflow.research, true); + assert.strictEqual(config.workflow.plan_check, true); + assert.strictEqual(config.workflow.verifier, true); + assert.strictEqual(config.workflow.nyquist_validation, true); + }); + + test('user choices override defaults', () => { + const choices = JSON.stringify({ + mode: 'yolo', + granularity: 'coarse', + parallelization: false, + commit_docs: false, + model_profile: 'quality', + workflow: { research: false, plan_check: false, verifier: true, nyquist_validation: false }, + }); + const result = runGsdTools(['config-new-project', choices], tmpDir); + assert.ok(result.success, `Command failed: ${result.error}`); + + const config = readConfig(tmpDir); + assert.strictEqual(config.mode, 'yolo'); + assert.strictEqual(config.granularity, 'coarse'); + assert.strictEqual(config.parallelization, false); + assert.strictEqual(config.commit_docs, false); + assert.strictEqual(config.model_profile, 'quality'); + assert.strictEqual(config.workflow.research, false); + assert.strictEqual(config.workflow.plan_check, false); + assert.strictEqual(config.workflow.verifier, true); + assert.strictEqual(config.workflow.nyquist_validation, false); + // Defaults still present for non-chosen keys + assert.strictEqual(config.git.branching_strategy, 'none'); + assert.strictEqual(typeof config.search_gitignored, 'boolean'); + }); + + test('works with empty choices — all defaults materialized', () => { + const result = runGsdTools(['config-new-project', '{}'], tmpDir); + assert.ok(result.success, `Command failed: ${result.error}`); + + const config = readConfig(tmpDir); + assert.strictEqual(config.model_profile, 'balanced'); + assert.strictEqual(config.commit_docs, true); + assert.strictEqual(config.parallelization, true); + assert.strictEqual(config.search_gitignored, false); + assert.ok(config.git && typeof config.git === 'object'); + assert.strictEqual(config.git.branching_strategy, 'none'); + assert.ok(config.workflow && typeof config.workflow === 'object'); + assert.strictEqual(config.workflow.nyquist_validation, true); + }); + + test('is idempotent — returns already_exists if config exists', () => { + // First call: create + const choices = JSON.stringify({ mode: 'yolo', granularity: 'fine' }); + const first = runGsdTools(['config-new-project', choices], tmpDir); + assert.ok(first.success, `First call failed: ${first.error}`); + const firstOut = JSON.parse(first.output); + assert.strictEqual(firstOut.created, true); + + // Second call: idempotent + const second = runGsdTools(['config-new-project', choices], tmpDir); + assert.ok(second.success, `Second call failed: ${second.error}`); + const secondOut = JSON.parse(second.output); + assert.strictEqual(secondOut.created, false); + assert.strictEqual(secondOut.reason, 'already_exists'); + + // Config unchanged + const config = readConfig(tmpDir); + assert.strictEqual(config.mode, 'yolo'); + assert.strictEqual(config.granularity, 'fine'); + }); + + test('auto_advance in workflow choices is preserved', () => { + const choices = JSON.stringify({ + mode: 'yolo', + granularity: 'standard', + workflow: { research: true, plan_check: true, verifier: true, nyquist_validation: true, auto_advance: true }, + }); + const result = runGsdTools(['config-new-project', choices], tmpDir); + assert.ok(result.success, `Command failed: ${result.error}`); + + const config = readConfig(tmpDir); + assert.strictEqual(config.workflow.auto_advance, true); + }); + + test('rejects invalid JSON choices', () => { + const result = runGsdTools(['config-new-project', '{not-json}'], tmpDir); + assert.strictEqual(result.success, false); + assert.ok(result.error.includes('Invalid JSON'), `Expected "Invalid JSON" in: ${result.error}`); + }); + + test('output JSON has created:true on success', () => { + const choices = JSON.stringify({ mode: 'interactive', granularity: 'standard' }); + const result = runGsdTools(['config-new-project', choices], tmpDir); + assert.ok(result.success, `Command failed: ${result.error}`); + const out = JSON.parse(result.output); + assert.strictEqual(out.created, true); + assert.strictEqual(out.path, '.planning/config.json'); + }); +}); +``` + +- [ ] **Step 1.2: Run failing tests to confirm they fail** + +```bash +cd /Users/diego/Dev/get-shit-done +node --test tests/config.test.cjs 2>&1 | grep -E "config-new-project|FAIL|Error" +``` + +Expected: All `config-new-project` tests fail with "config-new-project is not a valid command" or similar. + +- [ ] **Step 1.3: Implement `buildNewProjectConfig` and `cmdConfigNewProject` in config.cjs** + +In `get-shit-done/bin/lib/config.cjs`, add the following after the `validateKnownConfigKeyPath` function (around line 35) and before `ensureConfigFile`: + +```js +/** + * Build a fully-materialized config for a new project. + * + * Merges (in order of increasing priority): + * 1. Hardcoded defaults + * 2. User-level defaults from ~/.gsd/defaults.json (if present) + * 3. userChoices (the settings the user explicitly selected during new-project) + * + * Returns a plain object — does NOT write any files. + */ +function buildNewProjectConfig(cwd, userChoices) { + const choices = userChoices || {}; + const homedir = require('os').homedir(); + + // Detect Brave Search API key availability + const braveKeyFile = path.join(homedir, '.gsd', 'brave_api_key'); + const hasBraveSearch = !!(process.env.BRAVE_API_KEY || fs.existsSync(braveKeyFile)); + + // Load user-level defaults from ~/.gsd/defaults.json if available + const globalDefaultsPath = path.join(homedir, '.gsd', 'defaults.json'); + let userDefaults = {}; + try { + if (fs.existsSync(globalDefaultsPath)) { + userDefaults = JSON.parse(fs.readFileSync(globalDefaultsPath, 'utf-8')); + // Migrate deprecated "depth" key to "granularity" + if ('depth' in userDefaults && !('granularity' in userDefaults)) { + const depthToGranularity = { quick: 'coarse', standard: 'standard', comprehensive: 'fine' }; + userDefaults.granularity = depthToGranularity[userDefaults.depth] || userDefaults.depth; + delete userDefaults.depth; + try { + fs.writeFileSync(globalDefaultsPath, JSON.stringify(userDefaults, null, 2), 'utf-8'); + } catch {} + } + } + } catch { + // Ignore malformed global defaults + } + + const hardcoded = { + model_profile: 'balanced', + commit_docs: true, + parallelization: true, + search_gitignored: false, + brave_search: hasBraveSearch, + git: { + branching_strategy: 'none', + phase_branch_template: 'gsd/phase-{phase}-{slug}', + milestone_branch_template: 'gsd/{milestone}-{slug}', + }, + workflow: { + research: true, + plan_check: true, + verifier: true, + nyquist_validation: true, + }, + }; + + // Three-level merge: hardcoded <- userDefaults <- choices + return { + ...hardcoded, + ...userDefaults, + ...choices, + git: { + ...hardcoded.git, + ...(userDefaults.git || {}), + ...(choices.git || {}), + }, + workflow: { + ...hardcoded.workflow, + ...(userDefaults.workflow || {}), + ...(choices.workflow || {}), + }, + }; +} + +/** + * Command: create a fully-materialized .planning/config.json for a new project. + * + * Accepts user-chosen settings as a JSON string (the keys the user explicitly + * configured during /gsd-new-project). All remaining keys are filled from + * hardcoded defaults and optional ~/.gsd/defaults.json. + * + * Idempotent: if config.json already exists, returns { created: false }. + */ +function cmdConfigNewProject(cwd, choicesJson, raw) { + const configPath = path.join(cwd, '.planning', 'config.json'); + const planningDir = path.join(cwd, '.planning'); + + // Idempotent: don't overwrite existing config + if (fs.existsSync(configPath)) { + output({ created: false, reason: 'already_exists' }, raw, 'exists'); + return; + } + + // Parse user choices + let userChoices = {}; + if (choicesJson && choicesJson.trim() !== '') { + try { + userChoices = JSON.parse(choicesJson); + } catch (err) { + error('Invalid JSON for config-new-project: ' + err.message); + } + } + + // Ensure .planning directory exists + try { + if (!fs.existsSync(planningDir)) { + fs.mkdirSync(planningDir, { recursive: true }); + } + } catch (err) { + error('Failed to create .planning directory: ' + err.message); + } + + const config = buildNewProjectConfig(cwd, userChoices); + + try { + fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8'); + output({ created: true, path: '.planning/config.json' }, raw, 'created'); + } catch (err) { + error('Failed to write config.json: ' + err.message); + } +} +``` + +Also add `cmdConfigNewProject` to the `module.exports` at the bottom of `config.cjs`. + +- [ ] **Step 1.4: Run tests to verify they pass** + +```bash +cd /Users/diego/Dev/get-shit-done +node --test tests/config.test.cjs 2>&1 | tail -20 +``` + +Expected: All `config-new-project` tests pass. Existing tests still pass. + +- [ ] **Step 1.5: Commit** + +```bash +cd /Users/diego/Dev/get-shit-done +git add get-shit-done/bin/lib/config.cjs tests/config.test.cjs +git commit -m "feat: add config-new-project command for full config materialization" +``` + +--- + +## task 2: Register `config-new-project` in gsd-tools.cjs + +**Files:** + +- Modify: `get-shit-done/bin/gsd-tools.cjs` + +- [ ] **Step 2.1: Add the case to the switch in gsd-tools.cjs** + +After the `config-get` case (around line 401), add: + +```js + case 'config-new-project': { + config.cmdConfigNewProject(cwd, args[1], raw); + break; + } +``` + +Also update the usage string on line 178 to include `config-new-project`: + +Current: `...config-ensure-section, init` +New: `...config-ensure-section, config-new-project, init` + +- [ ] **Step 2.2: Smoke-test the CLI registration** + +```bash +cd /Users/diego/Dev/get-shit-done +node get-shit-done/bin/gsd-tools.cjs config-new-project '{"mode":"interactive","granularity":"standard"}' --cwd /tmp/gsd-smoke-$(date +%s) +``` + +Expected: outputs `{"created":true,"path":".planning/config.json"}` (or similar). + +Clean up: `rm -rf /tmp/gsd-smoke-*` + +- [ ] **Step 2.3: Run full test suite** + +```bash +cd /Users/diego/Dev/get-shit-done +node --test tests/config.test.cjs 2>&1 | tail -10 +``` + +Expected: All pass. + +- [ ] **Step 2.4: Commit** + +```bash +cd /Users/diego/Dev/get-shit-done +git add get-shit-done/bin/gsd-tools.cjs +git commit -m "feat: register config-new-project in gsd-tools CLI router" +``` + +--- + +## task 3: Update new-project.md workflow to use config-new-project + +**Files:** + +- Modify: `get-shit-done/workflows/new-project.md` + +This is the core change. Two places need updating: + +- **Step 2a** (auto mode config creation, around line 168–195) +- **Step 5** (interactive mode config creation, around line 470–498) + +- [ ] **Step 3.1: Update Step 2a (auto mode)** + +Find the block in Step 2a that creates config.json: + +```markdown +Create `.planning/config.json` with mode set to "yolo": + +```json +{ + "mode": "yolo", + "granularity": "[selected]", + ... +} +``` + +``` + +Replace the inline JSON write instruction with: + +```markdown +Create `.planning/config.json` using the CLI (fills in all defaults automatically): + +```bash +mkdir -p .planning +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-new-project "$(cat <<'CHOICES' +{ + "mode": "yolo", + "granularity": "[selected: coarse|standard|fine]", + "parallelization": [true|false], + "commit_docs": [true|false], + "model_profile": "[selected: simple|smart|genius|inherit]", + "workflow": { + "research": [true|false], + "plan_check": [true|false], + "verifier": [true|false], + "nyquist_validation": [true|false], + "auto_advance": true + } +} +CHOICES +)" +``` + +The command merges your selections with all runtime defaults (`search_gitignored`, `brave_search`, `git` section), producing a fully-materialized config. + +``` + +- [ ] **Step 3.2: Update Step 5 (interactive mode)** + +Find the block in Step 5 that creates config.json: + +```markdown +Create `.planning/config.json` with all settings: + +```json +{ + "mode": "yolo|interactive", + ... +} +``` + +``` + +Replace with: + +```markdown +Create `.planning/config.json` using the CLI (fills in all defaults automatically): + +```bash +mkdir -p .planning +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-new-project "$(cat <<'CHOICES' +{ + "mode": "[selected: yolo|interactive]", + "granularity": "[selected: coarse|standard|fine]", + "parallelization": [true|false], + "commit_docs": [true|false], + "model_profile": "[selected: simple|smart|genius|inherit]", + "workflow": { + "research": [true|false], + "plan_check": [true|false], + "verifier": [true|false], + "nyquist_validation": [true|false] + } +} +CHOICES +)" +``` + +The command merges your selections with all runtime defaults (`search_gitignored`, `brave_search`, `git` section), producing a fully-materialized config. + +``` + +- [ ] **Step 3.3: Verify the workflow file reads correctly** + +```bash +cd /Users/diego/Dev/get-shit-done +grep -n "config-new-project\|config\.json\|CHOICES" get-shit-done/workflows/new-project.md +``` + +Expected: 2 occurrences of `config-new-project` (one per step), no more inline JSON templates for config creation. + +- [ ] **Step 3.4: Commit** + +```bash +cd /Users/diego/Dev/get-shit-done +git add get-shit-done/workflows/new-project.md +git commit -m "feat: use config-new-project in new-project workflow for full config materialization" +``` + +--- + +## task 4: Validation + +- [ ] **Step 4.1: Run the full test suite** + +```bash +cd /Users/diego/Dev/get-shit-done +node --test tests/ 2>&1 | tail -30 +``` + +Expected: All tests pass (no regressions). + +- [ ] **Step 4.2: Manual end-to-end validation** + +Simulate what `new-project.md` does for a new project: + +```bash +# Create a fresh project dir +TMP=$(mktemp -d) +cd "$TMP" + +# Step 1 simulation: what init new-project returns +node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs init new-project --cwd "$TMP" + +# Step 5 simulation: create full config +node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs config-new-project '{ + "mode": "interactive", + "granularity": "standard", + "parallelization": true, + "commit_docs": true, + "model_profile": "balanced", + "workflow": { + "research": true, + "plan_check": true, + "verifier": true, + "nyquist_validation": true + } +}' --cwd "$TMP" + +# Verify the file has all 12 expected keys +echo "=== Generated config.json ===" +cat "$TMP/.planning/config.json" + +# Clean up +rm -rf "$TMP" +``` + +Expected output: a config.json with `mode`, `granularity`, `model_profile`, `commit_docs`, `parallelization`, `search_gitignored`, `brave_search`, `git` (3 sub-keys), `workflow` (4 sub-keys) — 12 top-level keys total (or 10 if counting `git` and `workflow` as single keys). + +- [ ] **Step 4.3: Verify idempotency** + +```bash +TMP=$(mktemp -d) +CHOICES='{"mode":"yolo","granularity":"coarse"}' + +node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs config-new-project "$CHOICES" --cwd "$TMP" +FIRST=$(cat "$TMP/.planning/config.json") + +# Second call should be no-op +node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs config-new-project "$CHOICES" --cwd "$TMP" +SECOND=$(cat "$TMP/.planning/config.json") + +[ "$FIRST" = "$SECOND" ] && echo "IDEMPOTENT: OK" || echo "IDEMPOTENT: FAIL" +rm -rf "$TMP" +``` + +Expected: `IDEMPOTENT: OK` + +- [ ] **Step 4.4: Verify loadConfig still reads the new format correctly** + +```bash +TMP=$(mktemp -d) +node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs config-new-project '{ + "mode":"yolo","granularity":"standard","parallelization":true,"commit_docs":true, + "model_profile":"balanced", + "workflow":{"research":true,"plan_check":false,"verifier":true,"nyquist_validation":true} +}' --cwd "$TMP" + +# loadConfig should correctly read plan_check (nested as workflow.plan_check) +node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs config-get workflow.plan_check --cwd "$TMP" +# Expected: false + +node /Users/diego/Dev/get-shit-done/get-shit-done/bin/gsd-tools.cjs config-get git.branching_strategy --cwd "$TMP" +# Expected: "none" + +rm -rf "$TMP" +``` + +- [ ] **Step 4.5: Final full test suite + commit** + +```bash +cd /Users/diego/Dev/get-shit-done +node --test tests/ 2>&1 | grep -E "pass|fail|error" | tail -5 +``` + +Expected: All pass, 0 failures. + +--- + +## Appendix: PR description for upstream + +``` +feat: materialize all config defaults at new-project initialization + +**Problem:** +`/gsd-new-project` creates `.planning/config.json` with only the 6 keys +the user explicitly chose during onboarding. Five additional keys +(`search_gitignored`, `brave_search`, `git.branching_strategy`, +`git.phase_branch_template`, `git.milestone_branch_template`) are resolved +silently by `loadConfig()` at runtime but never written to disk. + +This creates two problems: +1. **Discoverability**: users can't see or understand `git.branching_strategy` + without reading source code — it doesn't appear in their config. +2. **Implicit expansion**: the first time `/gsd-settings` or `config-set` + writes to the config, those keys still aren't added. The config only + reflects a fraction of the effective configuration. + +**Solution:** +Add `config-new-project` CLI command to `gsd-tools.cjs`. The command: +- Accepts user-chosen values as JSON +- Merges them with all runtime defaults (including env-detected `brave_search`) +- Writes the fully-materialized config in one shot + +Update `new-project.md` workflow (Steps 2a and 5) to call this command +instead of writing a hardcoded partial JSON template. Defaults now live in +exactly one place: `buildNewProjectConfig()` in `config.cjs`. + +**Why this is conservative:** +- No changes to `loadConfig()`, `ensureConfigFile()`, or any read path +- No new config keys introduced +- No semantic changes — same values the system was already resolving silently +- Fully backward-compatible: `loadConfig()` continues to handle both the old + partial format (existing projects) and the new full format +- Idempotent: calling `config-new-project` twice is safe +- No new user-facing flags + +**Why this improves discoverability:** +A developer opening `.planning/config.json` for the first time can now see +`git.branching_strategy: "none"` and immediately understand that branching +is available and configurable, without reading the GSD source. +``` diff --git a/gsd-opencode/docs/superpowers/specs/2026-03-20-multi-project-workspaces-design.md b/gsd-opencode/docs/superpowers/specs/2026-03-20-multi-project-workspaces-design.md new file mode 100644 index 0000000..e90cd34 --- /dev/null +++ b/gsd-opencode/docs/superpowers/specs/2026-03-20-multi-project-workspaces-design.md @@ -0,0 +1,185 @@ +# Multi-Project Workspaces (`/gsd-new-workspace`) + +**Issue:** #1241 +**Date:** 2026-03-20 +**Status:** Approved + +## Problem + +GSD is tied to one `.planning/` directory per working directory. Users with multiple independent projects (monorepo-style setups with 20+ child repos) or users needing feature branch isolation in the same repo cannot run parallel GSD sessions without manual cloning and state management. + +## Solution + +Three new commands that create, list, and remove **physical workspace directories** — each containing repo copies (git worktrees or clones) and an independent `.planning/` directory. + +This covers two use cases: +- **Multi-repo orchestration (A):** Workspace spanning multiple repos from a parent directory +- **Feature branch isolation (B):** Workspace containing a worktree of the current repo (special case of A where `--repos .`) + +## Commands + +### `/gsd-new-workspace` + +Creates a workspace directory with repo copies and its own `.planning/`. + +``` +/gsd-new-workspace --name feature-b --repos hr-ui,ZeymoAPI --path ~/workspaces/feature-b +/gsd-new-workspace --name feature-b --repos . --strategy worktree # same-repo isolation +``` + +**Arguments:** + +| Flag | Required | Default | Description | +|------|----------|---------|-------------| +| `--name` | Yes | — | Workspace name | +| `--repos` | No | Interactive selection | Comma-separated repo paths or names | +| `--path` | No | `~/gsd-workspaces/` | Target directory | +| `--strategy` | No | `worktree` | `worktree` (lightweight, shared .git) or `clone` (fully independent) | +| `--branch` | No | `workspace/` | Branch to checkout | +| `--auto` | No | false | Skip interactive questions, use defaults | + +### `/gsd-list-workspaces` + +Scans `~/gsd-workspaces/*/WORKSPACE.md` for workspace manifests. Displays table with name, path, repo count, GSD status (has PROJECT.md, current phase). + +### `/gsd-remove-workspace` + +Removes a workspace directory after confirmation. For worktree strategy, runs `git worktree remove` for each member repo first. Refuses if any repo has uncommitted changes. + +## Directory Structure + +``` +~/gsd-workspaces/feature-b/ # workspace root +├── WORKSPACE.md # manifest +├── .planning/ # independent GSD planning directory +│ ├── PROJECT.md # (if user ran /gsd-new-project) +│ ├── STATE.md +│ └── config.json +├── hr-ui/ # git worktree of source repo +│ └── (repo contents on workspace/feature-b branch) +└── ZeymoAPI/ # git worktree of source repo + └── (repo contents on workspace/feature-b branch) +``` + +Key properties: +- `.planning/` is at the workspace root, not inside any individual repo +- Each repo is a peer directory under the workspace root +- `WORKSPACE.md` is the only GSD-specific file at the root (besides `.planning/`) +- For `--strategy clone`, same structure but repos are full clones + +## WORKSPACE.md Format + +```markdown +# Workspace: feature-b + +Created: 2026-03-20 +Strategy: worktree + +## Member Repos + +| Repo | Source | Branch | Strategy | +|------|--------|--------|----------| +| hr-ui | /root/source/repos/hr-ui | workspace/feature-b | worktree | +| ZeymoAPI | /root/source/repos/ZeymoAPI | workspace/feature-b | worktree | + +## Notes + +[User can add context about what this workspace is for] +``` + +## Workflow + +### `/gsd-new-workspace` Workflow Steps + +1. **Setup** — Call `init new-workspace`, parse JSON context +2. **Gather inputs** — If `--name`/`--repos`/`--path` not provided, ask interactively. For repos, show child `.git` directories in cwd as options +3. **Validate** — Target path doesn't exist (or is empty). Source repos exist and are git repos +4. **Create workspace directory** — `mkdir -p ` +5. **Copy repos** — For each repo: + - Worktree: `git worktree add / -b workspace/` + - Clone: `git clone /` +6. **write WORKSPACE.md** — Manifest with source paths, strategy, branch +7. **Initialize .planning/** — `mkdir -p /.planning` +8. **Offer /gsd-new-project** — Ask if user wants to run project initialization in the new workspace +9. **Commit** — If commit_docs enabled, atomic commit of WORKSPACE.md +10. **Done** — Print workspace path and next steps + +### Init Function (`cmdInitNewWorkspace`) + +Detects: +- Child git repos in cwd (for interactive repo selection) +- Whether target path already exists +- Whether source repos have uncommitted changes +- Whether `git worktree` is available +- Default workspace base dir (`~/gsd-workspaces/`) + +Returns JSON with flags for workflow gating. + +## Error Handling + +### Validation Errors (Block Creation) + +- **Target path exists and is non-empty** — Error with suggestion to pick a different name/path +- **Source repo path doesn't exist or isn't a git repo** — Error listing which repos failed +- **`git worktree add` fails** (e.g., branch exists) — Fall back to `workspace/-` branch, or error if that also fails + +### Graceful Handling + +- **Source repo has uncommitted changes** — Warn but allow (worktrees checkout the branch fresh, don't copy working directory state) +- **Partial failure in multi-repo workspace** — Create workspace with repos that succeeded, report failures, write partial WORKSPACE.md +- **`--repos .` (current repo, case B)** — Detect repo name from directory name or git remote, use as subdirectory name + +### Remove-Workspace Safety + +- **Uncommitted changes in workspace repos** — Refuse removal, print which repos have changes +- **Worktree removal fails** (e.g., source repo deleted) — Warn and continue with directory cleanup +- **Confirmation** — Require explicit confirmation with workspace name typed out + +### List-Workspaces Edge Cases + +- **`~/gsd-workspaces/` doesn't exist** — "No workspaces found" +- **WORKSPACE.md exists but repos inside are gone** — Show workspace, mark repos as missing + +## Testing + +### Unit Tests (`tests/workspace.test.cjs`) + +1. `cmdInitNewWorkspace` returns correct JSON — detects child git repos, validates target path, detects git worktree availability +2. WORKSPACE.md generation — correct format with repo table, strategy, date +3. Repo discovery — identifies `.git` directories in cwd children, skips non-git directories and files +4. Validation — rejects existing non-empty target paths, rejects non-git source paths + +### Integration Tests (same file) + +5. Worktree creation — creates workspace, verifies repo directories are valid git worktrees +6. Clone creation — creates workspace, verifies repos are independent clones +7. List workspaces — creates two workspaces, verifies list output includes both +8. Remove workspace — creates workspace with worktrees, removes it, verifies cleanup +9. Partial failure — one valid repo + one invalid path, workspace created with valid repo only + +All tests use temp directories and clean up after themselves. Follow existing `node:test` + `node:assert` patterns. + +## Implementation Files + +| Component | Path | +|-----------|------| +| Command: new-workspace | `commands/gsd/new-workspace.md` | +| Command: list-workspaces | `commands/gsd/list-workspaces.md` | +| Command: remove-workspace | `commands/gsd/remove-workspace.md` | +| Workflow: new-workspace | `get-shit-done/workflows/new-workspace.md` | +| Workflow: list-workspaces | `get-shit-done/workflows/list-workspaces.md` | +| Workflow: remove-workspace | `get-shit-done/workflows/remove-workspace.md` | +| Init function | `get-shit-done/bin/lib/init.cjs` (add `cmdInitNewWorkspace`, `cmdInitListWorkspaces`, `cmdInitRemoveWorkspace`) | +| Routing | `get-shit-done/bin/gsd-tools.cjs` (add cases to init switch) | +| Tests | `tests/workspace.test.cjs` | + +## Design Decisions + +| Decision | Rationale | +|----------|-----------| +| Physical directories over logical registry | Filesystem is source of truth — matches GSD's existing cwd-based detection pattern | +| Worktree as default strategy | Lightweight (shared .git objects), fast to create, easy to clean up | +| `.planning/` at workspace root | Gives full isolation from individual repo planning. Each workspace is an independent GSD project | +| No central registry | Avoids state drift. `list-workspaces` scans the filesystem directly | +| Case B as special case of A | `--repos .` reuses the same machinery, no special feature-branch code needed | +| Default path `~/gsd-workspaces/` | Predictable location for `list-workspaces` to scan, keeps workspaces out of source repos | diff --git a/gsd-opencode/docs/workflow-discuss-mode.md b/gsd-opencode/docs/workflow-discuss-mode.md new file mode 100644 index 0000000..bcc9277 --- /dev/null +++ b/gsd-opencode/docs/workflow-discuss-mode.md @@ -0,0 +1,68 @@ +# Discuss Mode: Assumptions vs Interview + +GSD's discuss-phase has two modes for gathering implementation context before planning. + +## Modes + +### `discuss` (default) + +The original interview-style flow. OpenCode identifies gray areas in the phase, presents them +for selection, then asks ~4 questions per area. Good for: + +- Early phases where the codebase is new +- Phases where the user has strong opinions they want to express proactively +- Users who prefer guided, conversational context gathering + +### `assumptions` + +A codebase-first flow. OpenCode deeply analyzes the codebase via a subagent (reading 5-15 +relevant files), forms assumptions with evidence, and presents them for confirmation or +correction. Good for: + +- Established codebases with clear patterns +- Users who find the interview questions obvious +- Faster context gathering (~2-4 interactions vs ~15-20) + +## Configuration + +```bash +# Enable assumptions mode +gsd-tools config-set workflow.discuss_mode assumptions + +# Switch back to interview mode +gsd-tools config-set workflow.discuss_mode discuss +``` + +The setting is per-project (stored in `.planning/config.json`). + +## How Assumptions Mode Works + +1. **Init** — Same as discuss mode (load prior context, scout codebase, check todos) +2. **Deep analysis** — Explore subagent reads 5-15 codebase files related to the phase +3. **Surface assumptions** — Each assumption includes: + - What OpenCode would do and why (citing file paths) + - What goes wrong if the assumption is incorrect + - Confidence level (Confident / Likely / Unclear) +4. **Confirm or correct** — User reviews assumptions, selects any that need changing +5. **write CONTEXT.md** — Identical output format to discuss mode + +## Flag Compatibility + +| Flag | `discuss` mode | `assumptions` mode | +|------|----------------|-------------------| +| `--auto` | Auto-selects recommended answers | Skips confirm gate, auto-resolves Unclear items | +| `--batch` | Groups questions in batches | N/A (corrections already batched) | +| `--text` | Plain-text questions (remote sessions) | Plain-text questions (remote sessions) | +| `--analyze` | Shows trade-off tables per question | N/A (assumptions include evidence) | + +## Output + +Both modes produce identical CONTEXT.md with the same 6 sections: +- `` — Phase boundary +- `` — Locked implementation decisions +- `` — Specs/docs downstream agents must read +- `` — Reusable assets, patterns, integration points +- `` — User references and preferences +- `` — Ideas noted for future phases + +Downstream agents (researcher, planner, checker) consume this identically regardless of mode. diff --git a/gsd-opencode/docs/zh-CN/README.md b/gsd-opencode/docs/zh-CN/README.md new file mode 100644 index 0000000..acba856 --- /dev/null +++ b/gsd-opencode/docs/zh-CN/README.md @@ -0,0 +1,707 @@ +
+ +# GET SHIT DONE + +**一个轻量级且强大的元提示、上下文工程和规格驱动开发系统，支持 OpenCode、OpenCode、Gemini CLI 和 Codex。** + +**解决上下文衰减 —— 即 OpenCode 填充上下文窗口时发生的质量退化问题。** + +[![npm version](https://img.shields.io/npm/v/gsd-opencode?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/gsd-opencode) +[![npm downloads](https://img.shields.io/npm/dm/gsd-opencode?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/gsd-opencode) +[![Tests](https://img.shields.io/github/actions/workflow/status/gsd-build/get-shit-done/test.yml?branch=main&style=for-the-badge&logo=github&label=Tests)](https://github.com/rokicool/gsd-opencode/actions/workflows/test.yml) +[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/gsd) +[![X (Twitter)](https://img.shields.io/badge/X-@gsd__foundation-000000?style=for-the-badge&logo=x&logoColor=white)](https://x.com/gsd_foundation) +[![$GSD Token](https://img.shields.io/badge/$GSD-Dexscreener-1C1C1C?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48Y2lyY2xlIGN4PSIxMiIgY3k9IjEyIiByPSIxMCIgZmlsbD0iIzAwRkYwMCIvPjwvc3ZnPg==&logoColor=00FF00)](https://dexscreener.com/solana/dwudwjvan7bzkw9zwlbyv6kspdlvhwzrqy6ebk8xzxkv) +[![GitHub stars](https://img.shields.io/github/stars/gsd-build/get-shit-done?style=for-the-badge&logo=github&color=181717)](https://github.com/rokicool/gsd-opencode) +[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE) + +
+ +```bash +npx gsd-opencode@latest +``` + +**支持 Mac、Windows 和 Linux。** + +
+ +![GSD Install](../assets/terminal.svg) + +
+ +*"如果你清楚自己想要什么，它真的会帮你构建出来。不忽悠。"* + +*"我试过 SpecKit、OpenSpec 和 Taskmaster —— 这是我用过的效果最好的。"* + +*"这是我用过的 OpenCode 最强大的扩展。没有过度设计。真的就是把事情做完。"* + +
+ +**被 Amazon、Google、Shopify 和 Webflow 的工程师信赖使用。** + +[我为什么开发这个](#我为什么开发这个) · [工作原理](#工作原理) · [命令](#命令) · [为什么有效](#为什么有效) · [用户指南](USER-GUIDE.md) + +
+ +--- + +## 我为什么开发这个 + +我是一名独立开发者。我不写代码 —— OpenCode 写。 + +其他规格驱动开发工具确实存在，比如 BMAD、Speckit... 但它们似乎都把事情搞得比实际需要的复杂得多（冲刺会议、故事点、干系人同步、回顾、Jira 工作流），或者缺乏对你正在构建的东西的真正大局理解。我不是一个 50 人的软件公司。我不想搞企业级表演。我只是个想构建出好用的东西的创意人。 + +所以我开发了 GSD。复杂性在系统内部，不在你的工作流里。幕后是：上下文工程、XML 提示格式、子代理编排、状态管理。你看到的是：几个命令，用就完了。 + +系统给 OpenCode 提供了它完成工作**以及**验证工作所需的一切。我信任这个工作流。它就是做得好。 + +这就是它的本质。没有企业级角色扮演的废话。只是一个让 OpenCode 稳定可靠地构建酷东西的极其有效的系统。 + +— **TÂCHES** + +--- + +Vibecoding 名声不好。你描述想要什么，AI 生成代码，结果得到不一致的垃圾，规模一大就崩。 + +GSD 解决了这个问题。它是让 OpenCode 变得可靠的上下文工程层。描述你的想法，让系统提取它需要知道的一切，然后让 OpenCode 开始工作。 + +--- + +## 这个工具适合谁 + +想要描述需求然后正确构建出来的人 —— 不用假装自己在运营一个 50 人的工程组织。 + +--- + +## 快速开始 + +```bash +npx gsd-opencode@latest +``` + +安装程序会提示你选择： +1. **运行时** —— OpenCode、OpenCode、Gemini、Codex 或全部 +2. **位置** —— 全局（所有项目）或本地（仅当前项目） + +验证安装： +- OpenCode / Gemini: `/gsd-help` +- OpenCode: `/gsd-help` +- Codex: `$gsd-help` + +> [!NOTE] +> Codex 安装使用技能（`skills/gsd-*/SKILL.md`）而非自定义提示。 + +### 保持更新 + +GSD 快速迭代。定期更新： + +```bash +npx gsd-opencode@latest +``` + +
+非交互式安装（Docker、CI、脚本） + +```bash +# OpenCode +npx gsd-opencode --OpenCode --global # 安装到 $HOME/.config/opencode/ +npx gsd-opencode --OpenCode --local # 安装到 ./.OpenCode/ + +# OpenCode（开源，免费模型） +npx gsd-opencode --opencode --global # 安装到 ~/.config/opencode/ + +# Gemini CLI +npx gsd-opencode --gemini --global # 安装到 ~/.gemini/ + +# Codex（技能优先） +npx gsd-opencode --codex --global # 安装到 ~/.codex/ +npx gsd-opencode --codex --local # 安装到 ./.codex/ + +# 所有运行时 +npx gsd-opencode --all --global # 安装到所有目录 +``` + +使用 `--global`（`-g`）或 `--local`（`-l`）跳过位置提示。 +使用 `--OpenCode`、`--opencode`、`--gemini`、`--codex` 或 `--all` 跳过运行时提示。 + +
+ +
+开发安装 + +克隆仓库并本地运行安装程序： + +```bash +git clone https://github.com/rokicool/gsd-opencode.git +cd get-shit-done +node bin/install.js --OpenCode --local +``` + +安装到 `./.OpenCode/` 用于在贡献前测试修改。 + +
+ +### 推荐：跳过权限模式 + +GSD 设计为无摩擦自动化。运行 OpenCode 时使用： + +```bash +OpenCode --dangerously-skip-permissions +``` + +> [!TIP] +> 这是 GSD 的预期使用方式 —— 停下来 50 次批准 `date` 和 `git commit` 会失去意义。 + +
+替代方案：细粒度权限 + +如果你不想使用那个标志，在项目的 `.OpenCode/settings.json` 中添加： + +```json +{ + "permissions": { + "allow": [ + "bash(date:*)", + "bash(echo:*)", + "bash(cat:*)", + "bash(ls:*)", + "bash(mkdir:*)", + "bash(wc:*)", + "bash(head:*)", + "bash(tail:*)", + "bash(sort:*)", + "bash(grep:*)", + "bash(tr:*)", + "bash(git add:*)", + "bash(git commit:*)", + "bash(git status:*)", + "bash(git log:*)", + "bash(git diff:*)", + "bash(git tag:*)" + ] + } +} +``` + +
+ +--- + +## 工作原理 + +> **已有代码？** 先运行 `/gsd-map-codebase`。它会生成并行代理分析你的技术栈、架构、约定和关注点。然后 `/gsd-new-project` 就了解你的代码库了 —— 问题聚焦在你正在**添加**什么，规划会自动加载你的模式。 + +### 1. 初始化项目 + +``` +/gsd-new-project +``` + +一条命令，一个流程。系统： + +1. **提问** —— 问到完全理解你的想法为止（目标、约束、技术偏好、边缘情况） +2. **研究** —— 生成并行代理调查领域（可选但推荐） +3. **需求** —— 提取哪些是 v1、v2 和范围外 +4. **路线图** —— 创建映射到需求的阶段 + +你批准路线图。现在准备好构建了。 + +**创建：** `PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md`、`STATE.md`、`.planning/research/` + +--- + +### 2. 讨论阶段 + +``` +/gsd-discuss-phase 1 +``` + +**这是你塑造实现方式的地方。** + +你的路线图每个阶段有一两句话。这不足以按照**你**想象的方式构建东西。这一步在研究或规划之前捕获你的偏好。 + +系统分析阶段并根据正在构建的内容识别灰色区域： + +- **视觉功能** → 布局、密度、交互、空状态 +- **API/CLI** → 响应格式、标志、错误处理、详细程度 +- **内容系统** → 结构、语气、深度、流程 +- **组织任务** → 分组标准、命名、重复项、例外 + +对于你选择的每个领域，它会问到让你满意为止。输出 —— `CONTEXT.md` —— 直接输入接下来的两个步骤： + +1. **研究员读取它** —— 知道要调查什么模式（"用户想要卡片布局" → 研究卡片组件库） +2. **规划者读取它** —— 知道哪些决策已锁定（"无限滚动已决定" → 规划包含滚动处理） + +你在这里走得越深，系统构建的就越是你真正想要的。跳过它你会得到合理的默认值。使用它你会得到**你的**愿景。 + +**创建：** `{阶段号}-CONTEXT.md` + +--- + +### 3. 规划阶段 + +``` +/gsd-plan-phase 1 +``` + +系统： + +1. **研究** —— 调查如何实现这个阶段，由你的 CONTEXT.md 决策指导 +2. **规划** —— 创建 2-3 个带有 XML 结构的原子任务计划 +3. **验证** —— 根据需求检查计划，循环直到通过 + +每个计划足够小，可以在全新的上下文窗口中执行。没有退化，没有"我现在会更简洁"。 + +**创建：** `{阶段号}-RESEARCH.md`、`{阶段号}-{N}-PLAN.md` + +--- + +### 4. 执行阶段 + +``` +/gsd-execute-phase 1 +``` + +系统： + +1. **按波次运行计划** —— 可能的话并行，有依赖时顺序 +2. **每个计划全新上下文** —— 200k token 纯粹用于实现，零累积垃圾 +3. **每个任务提交** —— 每个任务都有自己的原子提交 +4. **根据目标验证** —— 检查代码库是否交付了阶段承诺的内容 + +离开，回来看到完成的工作和干净的 git 历史。 + +**波次执行工作原理：** + +计划根据依赖关系分组到"波次"。在每个波次内，计划并行运行。波次顺序执行。 + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ 阶段执行 │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ 波次 1 (并行) 波次 2 (并行) 波次 3 │ +│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ +│ │ 计划 01 │ │ 计划 02 │ → │ 计划 03 │ │ 计划 04 │ → │ 计划 05 │ │ +│ │ │ │ │ │ │ │ │ │ │ │ +│ │ 用户 │ │ 产品 │ │ 订单 │ │ 购物车 │ │ 结账 │ │ +│ │ 模型 │ │ 模型 │ │ API │ │ API │ │ UI │ │ +│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ +│ │ │ ↑ ↑ ↑ │ +│ └───────────┴──────────────┴───────────┘ │ │ +│ 依赖关系: 计划 03 需要计划 01 │ │ +│ 计划 04 需要计划 02 │ │ +│ 计划 05 需要计划 03 + 04 │ │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +**为什么波次重要：** +- 独立计划 → 同一波次 → 并行运行 +- 依赖计划 → 后续波次 → 等待依赖 +- 文件冲突 → 顺序计划或同一计划 + +这就是为什么"垂直切片"（计划 01: 用户功能端到端）比"水平分层"（计划 01: 所有模型，计划 02: 所有 API）并行化更好。 + +**创建：** `{阶段号}-{N}-SUMMARY.md`、`{阶段号}-VERIFICATION.md` + +--- + +### 5. 验证工作 + +``` +/gsd-verify-work 1 +``` + +**这是你确认它真的有效的地方。** + +自动化验证检查代码存在和测试通过。但功能是否按你预期的方式**工作**？这是你使用它的机会。 + +系统： + +1. **提取可测试交付物** —— 你现在应该能做什么 +2. **逐个引导你** —— "你能用邮箱登录吗？" 是/否，或描述有什么问题 +3. **自动诊断失败** —— 生成调试代理找根本原因 +4. **创建已验证的修复计划** —— 准备立即重新执行 + +如果一切通过，继续。如果有东西坏了，不用手动调试 —— 只需再次运行 `/gsd-execute-phase`，使用它创建的修复计划。 + +**创建：** `{阶段号}-UAT.md`，如果发现问题则创建修复计划 + +--- + +### 6. 循环 → 完成 → 下一个里程碑 + +``` +/gsd-discuss-phase 2 +/gsd-plan-phase 2 +/gsd-execute-phase 2 +/gsd-verify-work 2 +... +/gsd-complete-milestone +/gsd-new-milestone +``` + +循环 **讨论 → 规划 → 执行 → 验证** 直到里程碑完成。 + +如果你想在讨论期间更快速地输入，使用 `/gsd-discuss-phase --batch` 一次回答一组小问题，而不是一个一个来。 + +每个阶段都会获得你的输入（讨论）、适当的研究（规划）、干净的执行（执行）和人工验证（验证）。上下文保持新鲜。质量保持高水平。 + +当所有阶段完成后，`/gsd-complete-milestone` 归档里程碑并标记发布。 + +然后 `/gsd-new-milestone` 开始下一个版本 —— 与 `new-project` 相同的流程，但针对你现有的代码库。你描述接下来想构建什么，系统研究领域，你界定需求范围，它创建新的路线图。每个里程碑是一个干净的周期：定义 → 构建 → 发布。 + +--- + +### 快速模式 + +``` +/gsd-quick +``` + +**用于不需要完整规划的临时任务。** + +快速模式给你 GSD 保证（原子提交、状态跟踪）和更快的路径： + +- **相同代理** —— 规划者 + 执行者，相同质量 +- **跳过可选步骤** —— 无研究、无计划检查器、无验证器 +- **独立跟踪** —— 存放在 `.planning/quick/`，不是阶段 + +用于：bug 修复、小功能、配置更改、一次性任务。 + +``` +/gsd-quick +> 你想做什么？"在设置中添加深色模式切换" +``` + +**创建：** `.planning/quick/001-add-dark-mode-toggle/PLAN.md`、`SUMMARY.md` + +--- + +## 为什么有效 + +### 上下文工程 + +OpenCode 非常强大，**如果你**给它需要的上下文。大多数人没有。 + +GSD 为你处理： + +| 文件 | 作用 | +|------|------| +| `PROJECT.md` | 项目愿景，始终加载 | +| `research/` | 生态知识（技术栈、功能、架构、陷阱） | +| `REQUIREMENTS.md` | 界定 v1/v2 需求及阶段可追溯性 | +| `ROADMAP.md` | 你要去哪里，完成了什么 | +| `STATE.md` | 决策、阻塞项、位置 —— 跨会话记忆 | +| `PLAN.md` | 带有 XML 结构和验证步骤的原子任务 | +| `SUMMARY.md` | 发生了什么，改了什么，提交到历史 | +| `todos/` | 为后续工作捕获的想法和任务 | + +基于 OpenCode 质量退化的位置设置大小限制。保持在限制内，获得一致的卓越。 + +### XML 提示格式 + +每个计划都是为 OpenCode 优化的结构化 XML： + +```xml + + 创建登录端点 + src/app/api/auth/login/route.ts + + 使用 jose 处理 JWT（不用 jsonwebtoken - CommonJS 问题）。 + 根据 users 表验证凭据。 + 成功时返回 httpOnly cookie。 + + curl -X POST localhost:3000/api/auth/login 返回 200 + Set-Cookie + 有效凭据返回 cookie，无效返回 401 + +``` + +精确的指令。不猜测。内置验证。 + +### 多代理编排 + +每个阶段使用相同模式：轻量编排器生成专门代理，收集结果，路由到下一步。 + +| 阶段 | 编排器做 | 代理做 | +|-------|------------------|-----------| +| 研究 | 协调，呈现发现 | 4 个并行研究员调查技术栈、功能、架构、陷阱 | +| 规划 | 验证，管理迭代 | 规划者创建计划，检查器验证，循环直到通过 | +| 执行 | 分组为波次，跟踪进度 | 执行者并行实现，每个有全新 200k 上下文 | +| 验证 | 呈现结果，路由下一步 | 验证器根据目标检查代码库，调试器诊断失败 | + +编排器从不做重活。它生成代理，等待，整合结果。 + +**结果：** 你可以运行整个阶段 —— 深度研究、多个计划创建和验证、跨并行执行者编写数千行代码、根据目标自动化验证 —— 你的主上下文窗口保持在 30-40%。工作在全新的子代理上下文中完成。你的会话保持快速和响应。 + +### 原子 Git 提交 + +每个任务在完成后立即获得自己的提交： + +```bash +abc123f docs(08-02): 完成用户注册计划 +def456g feat(08-02): 添加邮箱确认流程 +hij789k feat(08-02): 实现密码哈希 +lmn012o feat(08-02): 创建注册端点 +``` + +> [!NOTE] +> **好处：** Git bisect 找到确切的失败任务。每个任务独立可回滚。未来会话中 OpenCode 的清晰历史。AI 自动化工作流中更好的可观察性。 + +每个提交都是精确的、可追溯的、有意义的。 + +### 模块化设计 + +- 向当前里程碑添加阶段 +- 在阶段之间插入紧急工作 +- 完成里程碑并重新开始 +- 调整计划而不重建一切 + +你永远不会被锁定。系统会适应。 + +--- + +## 命令 + +### 核心工作流 + +| 命令 | 作用 | +|---------|--------------| +| `/gsd-new-project [--auto]` | 完整初始化：提问 → 研究 → 需求 → 路线图 | +| `/gsd-discuss-phase [N] [--auto]` | 在规划前捕获实现决策 | +| `/gsd-plan-phase [N] [--auto]` | 阶段的研究 + 规划 + 验证 | +| `/gsd-execute-phase ` | 在并行波次中执行所有计划，完成后验证 | +| `/gsd-verify-work [N]` | 手动用户验收测试 ¹ | +| `/gsd-audit-milestone` | 验证里程碑达到了其完成定义 | +| `/gsd-complete-milestone` | 归档里程碑，标记发布 | +| `/gsd-new-milestone [name]` | 开始下一个版本：提问 → 研究 → 需求 → 路线图 | + +### 导航 + +| 命令 | 作用 | +|---------|--------------| +| `/gsd-progress` | 我在哪？接下来做什么？ | +| `/gsd-help` | 显示所有命令和使用指南 | +| `/gsd-update` | 更新 GSD 并预览变更日志 | +| `/gsd-join-discord` | 加入 GSD Discord 社区 | + +### 现有代码库 + +| 命令 | 作用 | +|---------|--------------| +| `/gsd-map-codebase` | 在 new-project 之前分析现有代码库 | + +### 阶段管理 + +| 命令 | 作用 | +|---------|--------------| +| `/gsd-add-phase` | 向路线图追加阶段 | +| `/gsd-insert-phase [N]` | 在阶段之间插入紧急工作 | +| `/gsd-remove-phase [N]` | 删除未来阶段，重新编号 | +| `/gsd-list-phase-assumptions [N]` | 规划前查看 OpenCode 的预期方法 | +| `/gsd-plan-milestone-gaps` | 创建阶段以填补审计发现的差距 | + +### 会话 + +| 命令 | 作用 | +|---------|--------------| +| `/gsd-pause-work` | 阶段中途停止时创建交接 | +| `/gsd-resume-work` | 从上次会话恢复 | + +### 工具 + +| 命令 | 作用 | +|---------|--------------| +| `/gsd-settings` | 配置模型配置文件和工作流代理 | +| `/gsd-set-profile ` | 切换模型配置文件（simple/smart/genius） | +| `/gsd-add-todo [desc]` | 捕获想法留待后用 | +| `/gsd-check-todos` | 列出待处理事项 | +| `/gsd-debug [desc]` | 带持久状态的系统化调试 | +| `/gsd-quick [--full] [--discuss]` | 用 GSD 保证执行临时任务（`--full` 添加计划检查和验证，`--discuss` 先收集上下文） | +| `/gsd-health [--repair]` | 验证 `.planning/` 目录完整性，用 `--repair` 自动修复 | + +¹ 由 Reddit 用户 OracleGreyBeard 贡献 + +--- + +## 配置 + +GSD 在 `.planning/config.json` 中存储项目设置。在 `/gsd-new-project` 期间配置或稍后用 `/gsd-settings` 更新。完整配置模式、工作流开关、git 分支选项和每个代理的模型分解，请参阅[用户指南](USER-GUIDE.md#配置参考)。 + +### 核心设置 + +| 设置 | 选项 | 默认值 | 控制内容 | +|---------|---------|---------|------------------| +| `mode` | `yolo`, `interactive` | `interactive` | 自动批准 vs 每步确认 | +| `granularity` | `coarse`, `standard`, `fine` | `standard` | 阶段粒度 —— 范围切分多细（阶段 × 计划） | + +### 模型配置 + +控制每个代理使用哪个 OpenCode 模型。平衡质量和 token 消耗。 + +| 配置 | 规划 | 执行 | 验证 | +|---------|----------|-----------|--------------| +| `quality` | Opus | Opus | Sonnet | +| `balanced`（默认） | Opus | Sonnet | Sonnet | +| `budget` | Sonnet | Sonnet | Haiku | + +切换配置： +``` +/gsd-set-profile budget +``` + +或通过 `/gsd-settings` 配置。 + +### 工作流代理 + +这些在规划/执行期间生成额外代理。它们提高质量但增加 token 和时间。 + +| 设置 | 默认值 | 作用 | +|---------|---------|--------------| +| `workflow.research` | `true` | 每个阶段规划前研究领域 | +| `workflow.plan_check` | `true` | 执行前验证计划是否达到阶段目标 | +| `workflow.verifier` | `true` | 执行后确认必须项已交付 | +| `workflow.auto_advance` | `false` | 自动链式执行 讨论 → 规划 → 执行 | + +使用 `/gsd-settings` 切换这些，或每次调用时覆盖： +- `/gsd-plan-phase --skip-research` +- `/gsd-plan-phase --skip-verify` + +### 执行 + +| 设置 | 默认值 | 控制内容 | +|---------|---------|------------------| +| `parallelization.enabled` | `true` | 同时运行独立计划 | +| `planning.commit_docs` | `true` | 在 git 中跟踪 `.planning/` | + +### Git 分支 + +控制 GSD 在执行期间如何处理分支。 + +| 设置 | 选项 | 默认值 | 作用 | +|---------|---------|---------|--------------| +| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | 分支创建策略 | +| `git.phase_branch_template` | 字符串 | `gsd/phase-{phase}-{slug}` | 阶段分支模板 | +| `git.milestone_branch_template` | 字符串 | `gsd/{milestone}-{slug}` | 里程碑分支模板 | + +**策略：** +- **`none`** —— 提交到当前分支（默认 GSD 行为） +- **`phase`** —— 每个阶段创建一个分支，阶段完成时合并 +- **`milestone`** —— 为整个里程碑创建一个分支，完成时合并 + +在里程碑完成时，GSD 提供 squash 合并（推荐）或带历史合并。 + +--- + +## 安全 + +### 保护敏感文件 + +GSD 的代码库映射和分析命令读取文件以了解你的项目。**保护包含密钥的文件**，将它们添加到 OpenCode 的拒绝列表： + +1. 打开 OpenCode 设置（`.OpenCode/settings.json` 或全局） +2. 将敏感文件模式添加到拒绝列表： + +```json +{ + "permissions": { + "deny": [ + "read(.env)", + "read(.env.*)", + "read(**/secrets/*)", + "read(**/*credential*)", + "read(**/*.pem)", + "read(**/*.key)" + ] + } +} +``` + +这完全阻止 OpenCode 读取这些文件，无论你运行什么命令。 + +> [!IMPORTANT] +> GSD 包含内置保护以防止提交密钥，但纵深防御是最佳实践。拒绝读取敏感文件作为第一道防线。 + +--- + +## 故障排除 + +**安装后找不到命令？** +- 重启运行时以重新加载命令/技能 +- 验证文件是否存在于 `$HOME/.config/opencode/commands/gsd/`（全局）或 `./.OpenCode/commands/gsd/`（本地） +- 对于 Codex，验证技能是否存在于 `~/.codex/skills/gsd-*/SKILL.md`（全局）或 `./.codex/skills/gsd-*/SKILL.md`（本地） + +**命令没有按预期工作？** +- 运行 `/gsd-help` 验证安装 +- 重新运行 `npx gsd-opencode` 重新安装 + +**更新到最新版本？** +```bash +npx gsd-opencode@latest +``` + +**使用 Docker 或容器化环境？** + +如果用波浪号路径（`$HOME/.config/opencode/...`）读取文件失败，在安装前设置 `CLAUDE_CONFIG_DIR`： +```bash +CLAUDE_CONFIG_DIR=/home/youruser/.OpenCode npx gsd-opencode --global +``` +这确保使用绝对路径而不是 `~`，后者在容器中可能无法正确展开。 + +### 卸载 + +完全删除 GSD： + +```bash +# 全局安装 +npx gsd-opencode --OpenCode --global --uninstall +npx gsd-opencode --opencode --global --uninstall +npx gsd-opencode --codex --global --uninstall + +# 本地安装（当前项目） +npx gsd-opencode --OpenCode --local --uninstall +npx gsd-opencode --opencode --local --uninstall +npx gsd-opencode --codex --local --uninstall +``` + +这删除所有 GSD 命令、代理、钩子和设置，同时保留你的其他配置。 + +--- + +## 社区移植 + +OpenCode、Gemini CLI 和 Codex 现在通过 `npx gsd-opencode` 原生支持。 + +这些社区移植开创了多运行时支持： + +| 项目 | 平台 | 描述 | +|---------|----------|-------------| +| [gsd-opencode](https://github.com/rokicool/gsd-opencode) | OpenCode | 原始 OpenCode 适配 | +| gsd-gemini (已归档) | Gemini CLI | 由 uberfuzzy 开发的原始 Gemini 适配 | + +--- + +## Star 历史 + + + + + + Star History Chart + + + +--- + +## 许可证 + +MIT 许可证。详见 [LICENSE](../LICENSE)。 + +--- + +
+ +**OpenCode 很强大。GSD 让它可靠。** + +
\ No newline at end of file diff --git a/gsd-opencode/docs/zh-CN/USER-GUIDE.md b/gsd-opencode/docs/zh-CN/USER-GUIDE.md new file mode 100644 index 0000000..e5906f9 --- /dev/null +++ b/gsd-opencode/docs/zh-CN/USER-GUIDE.md @@ -0,0 +1,492 @@ +# GSD 用户指南 + +工作流、故障排除和配置的详细参考。快速入门设置请参阅 [README](README.md)。 + +--- + +## 目录 + +- [工作流图解](#工作流图解) +- [命令参考](#命令参考) +- [配置参考](#配置参考) +- [使用示例](#使用示例) +- [故障排除](#故障排除) +- [恢复快速参考](#恢复快速参考) + +--- + +## 工作流图解 + +### 完整项目生命周期 + +``` + ┌──────────────────────────────────────────────────┐ + │ 新建项目 │ + │ /gsd-new-project │ + │ 提问 -> 研究 -> 需求 -> 路线图 │ + └─────────────────────────┬────────────────────────┘ + │ + ┌──────────────▼─────────────┐ + │ 每个阶段: │ + │ │ + │ ┌────────────────────┐ │ + │ │ /gsd-discuss-phase │ │ <- 锁定偏好 + │ └──────────┬─────────┘ │ + │ │ │ + │ ┌──────────▼─────────┐ │ + │ │ /gsd-plan-phase │ │ <- 研究 + 规划 + 验证 + │ └──────────┬─────────┘ │ + │ │ │ + │ ┌──────────▼─────────┐ │ + │ │ /gsd-execute-phase │ │ <- 并行执行 + │ └──────────┬─────────┘ │ + │ │ │ + │ ┌──────────▼─────────┐ │ + │ │ /gsd-verify-work │ │ <- 手动 UAT + │ └──────────┬─────────┘ │ + │ │ │ + │ 下一阶段?────────────┘ + │ │ 否 + └─────────────┼──────────────┘ + │ + ┌───────────────▼──────────────┐ + │ /gsd-audit-milestone │ + │ /gsd-complete-milestone │ + └───────────────┬──────────────┘ + │ + 另一个里程碑? + │ │ + 是 否 -> 完成! + │ + ┌───────▼──────────────┐ + │ /gsd-new-milestone │ + └──────────────────────┘ +``` + +### 规划代理协调 + +``` + /gsd-plan-phase N + │ + ├── 阶段研究员 (x4 并行) + │ ├── 技术栈研究员 + │ ├── 功能研究员 + │ ├── 架构研究员 + │ └── 陷阱研究员 + │ │ + │ ┌──────▼──────┐ + │ │ RESEARCH.md │ + │ └──────┬──────┘ + │ │ + │ ┌──────▼──────┐ + │ │ 规划者 │ <- 读取 PROJECT.md, REQUIREMENTS.md, + │ │ │ CONTEXT.md, RESEARCH.md + │ └──────┬──────┘ + │ │ + │ ┌──────▼───────────┐ ┌────────┐ + │ │ 计划检查器 │────>│ 通过? │ + │ └──────────────────┘ └───┬────┘ + │ │ + │ 是 │ 否 + │ │ │ │ + │ │ └───┘ (循环，最多 3 次) + │ │ + │ ┌─────▼──────┐ + │ │ PLAN 文件 │ + │ └────────────┘ + └── 完成 +``` + +### 验证架构 (Nyquist 层) + +在 plan-phase 研究期间，GSD 现在在任何代码编写之前将自动化测试覆盖率映射到每个阶段需求。这确保当 OpenCode 的执行者提交任务时，反馈机制已经存在可以在几秒钟内验证它。 + +研究员检测你现有的测试基础设施，将每个需求映射到特定的测试命令，并识别在实现开始之前必须创建的任何测试脚手架（波次 0 任务）。 + +计划检查器将其强制作为第 8 个验证维度：缺少自动化验证命令的计划将不会被批准。 + +**输出：** `{阶段}-VALIDATION.md` —— 阶段的反馈契约。 + +**禁用：** 在 `/gsd-settings` 中设置 `workflow.nyquist_validation: false`，用于测试基础设施不是重点的快速原型阶段。 + +### 追溯验证 (`/gsd-validate-phase`) + +对于在 Nyquist 验证存在之前执行的阶段，或只有传统测试套件的现有代码库，追溯审计并填补覆盖缺口： + +``` + /gsd-validate-phase N + | + +-- 检测状态 (VALIDATION.md 存在? SUMMARY.md 存在?) + | + +-- 发现: 扫描实现，将需求映射到测试 + | + +-- 分析缺口: 哪些需求缺少自动化验证? + | + +-- 呈现缺口计划供审批 + | + +-- 生成审计器: 生成测试，运行，调试（最多 3 次尝试） + | + +-- 更新 VALIDATION.md + | + +-- COMPLIANT -> 所有需求都有自动化检查 + +-- PARTIAL -> 部分缺口升级为仅手动 +``` + +审计器从不修改实现代码 —— 只修改测试文件和 VALIDATION.md。如果测试发现实现 bug，它会标记为升级让你处理。 + +**何时使用：** 在启用了 Nyquist 之前规划的阶段执行后，或在 `/gsd-audit-milestone` 发现 Nyquist 合规缺口后。 + +### 执行波次协调 + +``` + /gsd-execute-phase N + │ + ├── 分析计划依赖 + │ + ├── 波次 1 (独立计划): + │ ├── 执行者 A (全新 200K 上下文) -> 提交 + │ └── 执行者 B (全新 200K 上下文) -> 提交 + │ + ├── 波次 2 (依赖波次 1): + │ └── 执行者 C (全新 200K 上下文) -> 提交 + │ + └── 验证器 + └── 根据阶段目标检查代码库 + │ + ├── 通过 -> VERIFICATION.md (成功) + └── 失败 -> 问题记录到 /gsd-verify-work +``` + +### 现有代码库工作流 + +``` + /gsd-map-codebase + │ + ├── 技术栈映射器 -> codebase/STACK.md + ├── 架构映射器 -> codebase/ARCHITECTURE.md + ├── 约定映射器 -> codebase/CONVENTIONS.md + └── 关注点映射器 -> codebase/CONCERNS.md + │ + ┌───────▼──────────┐ + │ /gsd-new-project │ <- 问题聚焦于你正在添加的内容 + └──────────────────┘ +``` + +--- + +## 命令参考 + +### 核心工作流 + +| 命令 | 用途 | 何时使用 | +|---------|---------|-------------| +| `/gsd-new-project` | 完整项目初始化：提问、研究、需求、路线图 | 新项目开始时 | +| `/gsd-new-project --auto @idea.md` | 从文档自动初始化 | 有现成的 PRD 或想法文档 | +| `/gsd-discuss-phase [N]` | 捕获实现决策 | 规划前，塑造构建方式 | +| `/gsd-plan-phase [N]` | 研究 + 规划 + 验证 | 执行阶段前 | +| `/gsd-execute-phase ` | 在并行波次中执行所有计划 | 规划完成后 | +| `/gsd-verify-work [N]` | 带自动诊断的手动 UAT | 执行完成后 | +| `/gsd-audit-milestone` | 验证里程碑达到其完成定义 | 完成里程碑前 | +| `/gsd-complete-milestone` | 归档里程碑，标记发布 | 所有阶段已验证 | +| `/gsd-new-milestone [name]` | 开始下一个版本周期 | 完成里程碑后 | + +### 导航 + +| 命令 | 用途 | 何时使用 | +|---------|---------|-------------| +| `/gsd-progress` | 显示状态和下一步 | 任何时候 -- "我在哪?" | +| `/gsd-resume-work` | 从上次会话恢复完整上下文 | 开始新会话 | +| `/gsd-pause-work` | 保存上下文交接 | 阶段中途停止 | +| `/gsd-help` | 显示所有命令 | 快速参考 | +| `/gsd-update` | 更新 GSD 并预览变更日志 | 检查新版本 | +| `/gsd-join-discord` | 打开 Discord 社区邀请 | 问题或社区 | + +### 阶段管理 + +| 命令 | 用途 | 何时使用 | +|---------|---------|-------------| +| `/gsd-add-phase` | 向路线图追加新阶段 | 初始规划后范围增长 | +| `/gsd-insert-phase [N]` | 插入紧急工作（小数编号） | 里程碑中途紧急修复 | +| `/gsd-remove-phase [N]` | 删除未来阶段并重新编号 | 移除某个功能 | +| `/gsd-list-phase-assumptions [N]` | 预览 OpenCode 的预期方法 | 规划前，验证方向 | +| `/gsd-plan-milestone-gaps` | 为审计缺口创建阶段 | 审计发现缺失项后 | +| `/gsd-research-phase [N]` | 仅深度生态研究 | 复杂或不熟悉的领域 | + +### 现有代码库和工具 + +| 命令 | 用途 | 何时使用 | +|---------|---------|-------------| +| `/gsd-map-codebase` | 分析现有代码库 | 在现有代码上运行 `/gsd-new-project` 之前 | +| `/gsd-quick` | 带 GSD 保证的临时任务 | Bug 修复、小功能、配置更改 | +| `/gsd-debug [desc]` | 带持久状态的系统化调试 | 出问题时 | +| `/gsd-add-todo [desc]` | 捕获想法留待后用 | 会话期间想到什么 | +| `/gsd-check-todos` | 列出待处理事项 | 查看捕获的想法 | +| `/gsd-settings` | 配置工作流开关和模型配置 | 更改模型、切换代理 | +| `/gsd-set-profile ` | 快速切换配置 | 更改成本/质量权衡 | +| `/gsd-reapply-patches` | 更新后恢复本地修改 | 如果你有本地编辑，在 `/gsd-update` 后 | + +--- + +## 配置参考 + +GSD 在 `.planning/config.json` 中存储项目设置。在 `/gsd-new-project` 期间配置或稍后用 `/gsd-settings` 更新。 + +### 完整 config.json 模式 + +```json +{ + "mode": "interactive", + "granularity": "standard", + "model_profile": "balanced", + "planning": { + "commit_docs": true, + "search_gitignored": false + }, + "workflow": { + "research": true, + "plan_check": true, + "verifier": true, + "nyquist_validation": true + }, + "git": { + "branching_strategy": "none", + "phase_branch_template": "gsd/phase-{phase}-{slug}", + "milestone_branch_template": "gsd/{milestone}-{slug}" + } +} +``` + +### 核心设置 + +| 设置 | 选项 | 默认值 | 控制内容 | +|---------|---------|---------|------------------| +| `mode` | `interactive`, `yolo` | `interactive` | `yolo` 自动批准决策；`interactive` 每步确认 | +| `granularity` | `coarse`, `standard`, `fine` | `standard` | 阶段粒度：范围切分多细（3-5、5-8 或 8-12 个阶段） | +| `model_profile` | `quality`, `balanced`, `budget` | `balanced` | 每个代理的模型层级（见下表） | + +### 规划设置 + +| 设置 | 选项 | 默认值 | 控制内容 | +|---------|---------|---------|------------------| +| `planning.commit_docs` | `true`, `false` | `true` | `.planning/` 文件是否提交到 git | +| `planning.search_gitignored` | `true`, `false` | `false` | 在广泛搜索中添加 `--no-ignore` 以包含 `.planning/` | + +> **注意：** 如果 `.planning/` 在 `.gitignore` 中，无论配置值如何，`commit_docs` 自动为 `false`。 + +### 工作流开关 + +| 设置 | 选项 | 默认值 | 控制内容 | +|---------|---------|---------|------------------| +| `workflow.research` | `true`, `false` | `true` | 规划前的领域调查 | +| `workflow.plan_check` | `true`, `false` | `true` | 计划验证循环（最多 3 次迭代） | +| `workflow.verifier` | `true`, `false` | `true` | 根据阶段目标的执行后验证 | +| `workflow.nyquist_validation` | `true`, `false` | `true` | plan-phase 期间的验证架构研究；第 8 个计划检查维度 | + +在熟悉的领域或需要节省 token 时禁用这些以加速阶段。 + +### Git 分支 + +| 设置 | 选项 | 默认值 | 控制内容 | +|---------|---------|---------|------------------| +| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | 何时以及如何创建分支 | +| `git.phase_branch_template` | 模板字符串 | `gsd/phase-{phase}-{slug}` | 阶段策略的分支名 | +| `git.milestone_branch_template` | 模板字符串 | `gsd/{milestone}-{slug}` | 里程碑策略的分支名 | + +**分支策略说明：** + +| 策略 | 创建分支 | 范围 | 适用于 | +|----------|---------------|-------|----------| +| `none` | 从不 | N/A | 独立开发、简单项目 | +| `phase` | 每次 `execute-phase` | 每个阶段一个分支 | 每阶段代码审查、细粒度回滚 | +| `milestone` | 第一次 `execute-phase` | 所有阶段共享一个分支 | 发布分支、每个版本一个 PR | + +**模板变量：** `{phase}` = 零填充数字（如 "03"），`{slug}` = 小写连字符名称，`{milestone}` = 版本（如 "v1.0"）。 + +### 模型配置（每个代理分解） + +| 代理 | `quality` | `balanced` | `budget` | +|-------|-----------|------------|----------| +| gsd-planner | Opus | Opus | Sonnet | +| gsd-roadmapper | Opus | Sonnet | Sonnet | +| gsd-executor | Opus | Sonnet | Sonnet | +| gsd-phase-researcher | Opus | Sonnet | Haiku | +| gsd-project-researcher | Opus | Sonnet | Haiku | +| gsd-research-synthesizer | Sonnet | Sonnet | Haiku | +| gsd-debugger | Opus | Sonnet | Sonnet | +| gsd-codebase-mapper | Sonnet | Haiku | Haiku | +| gsd-verifier | Sonnet | Sonnet | Haiku | +| gsd-plan-checker | Sonnet | Sonnet | Haiku | +| gsd-integration-checker | Sonnet | Sonnet | Haiku | + +**配置理念：** +- **quality** —— 所有决策代理使用 Opus，只读验证使用 Sonnet。有配额可用且工作关键时使用。 +- **balanced** —— 仅规划（架构决策发生的地方）使用 Opus，其他全部使用 Sonnet。这是默认，有充分理由。 +- **budget** —— 编写代码的使用 Sonnet，研究和验证使用 Haiku。大量工作或不太关键的阶段使用。 + +--- + +## 使用示例 + +### 新项目（完整周期） + +```bash +OpenCode --dangerously-skip-permissions +/gsd-new-project # 回答问题，配置，批准路线图 +/new +/gsd-discuss-phase 1 # 锁定你的偏好 +/gsd-plan-phase 1 # 研究 + 规划 + 验证 +/gsd-execute-phase 1 # 并行执行 +/gsd-verify-work 1 # 手动 UAT +/new +/gsd-discuss-phase 2 # 对每个阶段重复 +... +/gsd-audit-milestone # 检查所有内容已发布 +/gsd-complete-milestone # 归档，标记，完成 +``` + +### 从现有文档创建新项目 + +```bash +/gsd-new-project --auto @prd.md # 从你的文档自动运行研究/需求/路线图 +/new +/gsd-discuss-phase 1 # 从这里开始正常流程 +``` + +### 现有代码库 + +```bash +/gsd-map-codebase # 分析现有内容（并行代理） +/gsd-new-project # 问题聚焦于你正在添加的内容 +# （从这里开始正常阶段工作流） +``` + +### 快速 Bug 修复 + +```bash +/gsd-quick +> "修复移动端 Safari 上登录按钮无响应的问题" +``` + +### 中断后恢复 + +```bash +/gsd-progress # 查看你停在哪和接下来做什么 +# 或 +/gsd-resume-work # 从上次会话完整恢复上下文 +``` + +### 准备发布 + +```bash +/gsd-audit-milestone # 检查需求覆盖率，检测存根 +/gsd-plan-milestone-gaps # 如果审计发现缺口，创建阶段来填补 +/gsd-complete-milestone # 归档，标记，完成 +``` + +### 速度与质量预设 + +| 场景 | 模式 | 粒度 | 配置 | 研究 | 计划检查 | 验证器 | +|----------|------|-------|---------|----------|------------|----------| +| 原型开发 | `yolo` | `coarse` | `budget` | 关 | 关 | 关 | +| 正常开发 | `interactive` | `standard` | `balanced` | 开 | 开 | 开 | +| 生产环境 | `interactive` | `fine` | `quality` | 开 | 开 | 开 | + +### 里程碑中途范围变更 + +```bash +/gsd-add-phase # 向路线图追加新阶段 +# 或 +/gsd-insert-phase 3 # 在阶段 3 和 4 之间插入紧急工作 +# 或 +/gsd-remove-phase 7 # 移除阶段 7 并重新编号 +``` + +--- + +## 故障排除 + +### "项目已初始化" + +你运行了 `/gsd-new-project` 但 `.planning/PROJECT.md` 已存在。这是安全检查。如果你想重新开始，先删除 `.planning/` 目录。 + +### 长会话期间上下文退化 + +在主要命令之间清除上下文窗口：OpenCode 中的 `/new`。GSD 设计围绕全新上下文 —— 每个子代理获得干净的 200K 窗口。如果主会话质量下降，清除并使用 `/gsd-resume-work` 或 `/gsd-progress` 恢复状态。 + +### 计划看起来错误或不一致 + +在规划前运行 `/gsd-discuss-phase [N]`。大多数计划质量问题来自 OpenCode 做出了 `CONTEXT.md` 本可以防止的假设。你也可以运行 `/gsd-list-phase-assumptions [N]` 在提交计划前查看 OpenCode 打算做什么。 + +### 执行失败或产生存根 + +检查计划是否太雄心勃勃。计划最多应有 2-3 个任务。如果任务太大，它们超出了单个上下文窗口可以可靠产生的内容。用更小的范围重新规划。 + +### 忘记你在哪里 + +运行 `/gsd-progress`。它读取所有状态文件，准确告诉你位置和下一步。 + +### 执行后需要更改某些内容 + +不要重新运行 `/gsd-execute-phase`。使用 `/gsd-quick` 进行针对性修复，或用 `/gsd-verify-work` 通过 UAT 系统识别和修复问题。 + +### 模型成本太高 + +切换到 budget 配置：`/gsd-set-profile budget`。如果领域对你（或 OpenCode）熟悉，通过 `/gsd-settings` 禁用研究和计划检查代理。 + +### 处理敏感/私有项目 + +在 `/gsd-new-project` 期间或通过 `/gsd-settings` 设置 `commit_docs: false`。将 `.planning/` 添加到 `.gitignore`。规划工件保留在本地，从不接触 git。 + +### GSD 更新覆盖了我的本地更改 + +从 v1.17 开始，安装程序将本地修改的文件备份到 `gsd-local-patches/`。运行 `/gsd-reapply-patches` 将你的更改合并回来。 + +### 子代理似乎失败但工作已完成 + +存在 OpenCode 分类 bug 的已知解决方法。GSD 的编排器（execute-phase、quick）在报告失败前抽查实际输出。如果你看到失败消息但提交已创建，检查 `git log` —— 工作可能已成功。 + +--- + +## 恢复快速参考 + +| 问题 | 解决方案 | +|---------|----------| +| 丢失上下文 / 新会话 | `/gsd-resume-work` 或 `/gsd-progress` | +| 阶段出错 | `git revert` 阶段提交，然后重新规划 | +| 需要更改范围 | `/gsd-add-phase`、`/gsd-insert-phase` 或 `/gsd-remove-phase` | +| 里程碑审计发现缺口 | `/gsd-plan-milestone-gaps` | +| 出问题了 | `/gsd-debug "描述"` | +| 快速针对性修复 | `/gsd-quick` | +| 计划与你的愿景不符 | `/gsd-discuss-phase [N]` 然后重新规划 | +| 成本过高 | `/gsd-set-profile budget` 和 `/gsd-settings` 关闭代理 | +| 更新破坏了本地更改 | `/gsd-reapply-patches` | + +--- + +## 项目文件结构 + +供参考，这是 GSD 在你的项目中创建的内容： + +``` +.planning/ + PROJECT.md # 项目愿景和上下文（始终加载） + REQUIREMENTS.md # 界定 v1/v2 需求及 ID + ROADMAP.md # 带状态跟踪的阶段分解 + STATE.md # 决策、阻塞项、会话记忆 + config.json # 工作流配置 + MILESTONES.md # 已完成里程碑归档 + research/ # 来自 /gsd-new-project 的领域研究 + todos/ + pending/ # 等待处理的捕获想法 + done/ # 已完成的待办事项 + debug/ # 活跃调试会话 + resolved/ # 已归档的调试会话 + codebase/ # 现有代码库映射（来自 /gsd-map-codebase） + phases/ + XX-phase-name/ + XX-YY-PLAN.md # 原子执行计划 + XX-YY-SUMMARY.md # 执行结果和决策 + CONTEXT.md # 你的实现偏好 + RESEARCH.md # 生态研究发现 + VERIFICATION.md # 执行后验证结果 +``` \ No newline at end of file diff --git a/gsd-opencode/docs/zh-CN/references/checkpoints.md b/gsd-opencode/docs/zh-CN/references/checkpoints.md new file mode 100644 index 0000000..37113f9 --- /dev/null +++ b/gsd-opencode/docs/zh-CN/references/checkpoints.md @@ -0,0 +1,450 @@ +# 检查点 + +计划自主执行。检查点用于规范化需要人工验证或决策的交互点。 + +**核心原则：** OpenCode 用 CLI/API 自动化一切。检查点用于验证和决策，而非手动工作。 + +**黄金法则：** +1. **如果 OpenCode 能运行，OpenCode 就运行** - 绝不让用户执行 CLI 命令、启动服务器或运行构建 +2. **OpenCode 设置验证环境** - 启动开发服务器、填充数据库、配置环境变量 +3. **用户只做需要人工判断的事** - 视觉检查、UX 评估、"这个感觉对吗？" +4. **密钥来自用户，自动化来自 OpenCode** - 询问 API 密钥，然后 OpenCode 通过 CLI 使用它们 +5. **自动模式绕过验证/决策检查点** — 当 config 中 `workflow._auto_chain_active` 或 `workflow.auto_advance` 为 true 时：human-verify 自动批准，decision 自动选择第一个选项，human-action 仍会停止（认证门控无法自动化） + +## 检查点类型 + +### checkpoint:human-verify（最常见 - 90%） + +**何时使用：** OpenCode 完成自动化工作，人工确认其正常工作。 + +**用于：** +- 视觉 UI 检查（布局、样式、响应式） +- 交互流程（点击向导、测试用户流程） +- 功能验证（功能按预期工作） +- 音频/视频播放质量 +- 动画流畅度 +- 无障碍测试 + +**结构：** +```xml + + [OpenCode 自动化并部署/构建的内容] + + [测试的确切步骤 - URL、命令、预期行为] + + [如何继续 - "approved"、"yes" 或描述问题] + +``` + +**示例：UI 组件（展示关键模式：OpenCode 在检查点之前启动服务器）** +```xml + + 构建响应式仪表板布局 + src/components/Dashboard.tsx, src/app/dashboard/page.tsx + 创建带侧边栏、标题和内容区域的仪表板。使用 Tailwind 响应式类处理移动端。 + npm run build 成功，无 TypeScript 错误 + 仪表板组件构建无错误 + + + + 启动开发服务器用于验证 + 在后台运行 `npm run dev`，等待 "ready" 消息，捕获端口 + curl http://localhost:3000 返回 200 + 开发服务器运行于 http://localhost:3000 + + + + 响应式仪表板布局 - 开发服务器运行于 http://localhost:3000 + + 访问 http://localhost:3000/dashboard 并验证： + 1. 桌面端 (>1024px): 左侧边栏，右侧内容，顶部标题 + 2. 平板端 (768px): 侧边栏折叠为汉堡菜单 + 3. 移动端 (375px): 单列布局，出现底部导航 + 4. 任何尺寸无布局偏移或水平滚动 + + 输入 "approved" 或描述布局问题 + +``` + +### checkpoint:decision（9%） + +**何时使用：** 人工必须做出影响实现方向的选择。 + +**用于：** +- 技术选型（哪个认证提供商、哪个数据库） +- 架构决策（monorepo 还是独立仓库） +- 设计选择（配色方案、布局方式） +- 功能优先级（构建哪个变体） +- 数据模型决策（模式结构） + +**结构：** +```xml + + [正在决策的内容] + [为什么这个决策重要] + + + + + [如何表明选择] + +``` + +**示例：认证提供商选择** +```xml + + 选择认证提供商 + + 应用需要用户认证。三个可靠选项各有权衡。 + + + + + + + 选择：supabase、clerk 或 nextauth + +``` + +### checkpoint:human-action（1% - 罕见） + +**何时使用：** 操作没有 CLI/API 且需要仅人工交互，或者 OpenCode 在自动化过程中遇到认证门控。 + +**仅用于：** +- **认证门控** - OpenCode 尝试了 CLI/API 但需要凭证（这不是失败） +- 邮箱验证链接（点击邮件） +- 短信两步验证码（手机验证） +- 人工账户审批（平台需要人工审核） +- 信用卡 3D Secure 流程（基于 Web 的支付授权） +- OAuth 应用审批（基于 Web 的审批） + +**不要用于预定的手动工作：** +- 部署（使用 CLI - 如需要则认证门控） +- 创建 webhooks/数据库（使用 API/CLI - 如需要则认证门控） +- 运行构建/测试（使用 bash 工具） +- 创建文件（使用 write 工具） + +**结构：** +```xml + + [人工必须做什么 - OpenCode 已完成所有可自动化的] + + [OpenCode 已自动化的内容] + [需要人工操作的一件事] + + [OpenCode 之后可以检查的内容] + [如何继续] + +``` + +**示例：认证门控（动态检查点）** +```xml + + 部署到 Vercel + .vercel/, vercel.json + 运行 `vercel --yes` 进行部署 + vercel ls 显示部署，curl 返回 200 + + + + + + 认证 Vercel CLI 以便我继续部署 + + 我尝试部署但收到认证错误。 + 运行：vercel login + 这将打开你的浏览器 - 完成认证流程。 + + vercel whoami 返回你的账户邮箱 + 认证完成后输入 "done" + + + + + + 重试 Vercel 部署 + 运行 `vercel --yes`（已认证） + vercel ls 显示部署，curl 返回 200 + +``` + +**关键区别：** 认证门控是 OpenCode 遇到认证错误时动态创建的。不是预定的 — OpenCode 先自动化，只有在被阻止时才请求凭证。 + +## 执行协议 + +当 OpenCode 遇到 `type="checkpoint:*"` 时： + +1. **立即停止** - 不继续下一个任务 +2. **清晰显示检查点** 使用下面的格式 +3. **等待用户响应** - 不幻想完成 +4. **如可能则验证** - 检查文件、运行测试、任何指定的内容 +5. **恢复执行** - 仅在确认后继续下一个任务 + +**对于 checkpoint:human-verify:** +``` +╔═══════════════════════════════════════════════════════╗ +║ CHECKPOINT: 需要验证 ║ +╚═══════════════════════════════════════════════════════╝ + +进度: 5/8 任务完成 +任务: 响应式仪表板布局 + +已构建: /dashboard 的响应式仪表板 + +如何验证: + 1. 访问: http://localhost:3000/dashboard + 2. 桌面端 (>1024px): 侧边栏可见，内容填充剩余空间 + 3. 平板端 (768px): 侧边栏折叠为图标 + 4. 移动端 (375px): 侧边栏隐藏，出现汉堡菜单 + +──────────────────────────────────────────────────────── +→ 你的操作: 输入 "approved" 或描述问题 +──────────────────────────────────────────────────────── +``` + +**对于 checkpoint:decision:** +``` +╔═══════════════════════════════════════════════════════╗ +║ CHECKPOINT: 需要决策 ║ +╚═══════════════════════════════════════════════════════╝ + +进度: 2/6 任务完成 +任务: 选择认证提供商 + +决策: 我们应该使用哪个认证提供商？ + +上下文: 需要用户认证。三个选项各有权衡。 + +选项: + 1. supabase - 与我们的数据库内置集成，免费额度 + 优点: 行级安全集成，慷慨的免费额度 + 缺点: UI 定制性较差，生态锁定 + + 2. clerk - 最佳 DX，10k 用户后付费 + 优点: 精美的预构建 UI，优秀文档 + 缺点: 供应商锁定，规模化时价格问题 + + 3. nextauth - 自托管，最大控制权 + 优点: 免费，无供应商锁定，广泛采用 + 缺点: 更多设置工作，自行 DIY 安全更新 + +──────────────────────────────────────────────────────── +→ 你的操作: 选择 supabase、clerk 或 nextauth +──────────────────────────────────────────────────────── +``` + +## 认证门控 + +**认证门控 = OpenCode 尝试了 CLI/API，收到认证错误。** 不是失败 — 是需要人工输入来解除阻止的门控。 + +**模式：** OpenCode 尝试自动化 → 认证错误 → 创建 checkpoint:human-action → 用户认证 → OpenCode 重试 → 继续 + +**门控协议：** +1. 认识到这不是失败 - 缺少认证是正常的 +2. 停止当前任务 - 不要反复重试 +3. 动态创建 checkpoint:human-action +4. 提供确切的认证步骤 +5. 验证认证有效 +6. 重试原始任务 +7. 正常继续 + +**关键区别：** +- 预定的检查点："我需要你做 X"（错误 - OpenCode 应该自动化） +- 认证门控："我尝试自动化 X 但需要凭证"（正确 - 解除自动化阻止） + +## 自动化参考 + +**规则：** 如果有 CLI/API，OpenCode 就做。绝不让人工执行可自动化的工作。 + +### 服务 CLI 参考 + +| 服务 | CLI/API | 关键命令 | 认证门控 | +|------|---------|----------|----------| +| Vercel | `vercel` | `--yes`, `env add`, `--prod`, `ls` | `vercel login` | +| Railway | `railway` | `init`, `up`, `variables set` | `railway login` | +| Fly | `fly` | `launch`, `deploy`, `secrets set` | `fly auth login` | +| Stripe | `stripe` + API | `listen`, `trigger`, API 调用 | .env 中的 API key | +| Supabase | `supabase` | `init`, `link`, `db push`, `gen types` | `supabase login` | +| Upstash | `upstash` | `redis create`, `redis get` | `upstash auth login` | +| PlanetScale | `pscale` | `database create`, `branch create` | `pscale auth login` | +| GitHub | `gh` | `repo create`, `pr create`, `secret set` | `gh auth login` | +| Node | `npm`/`pnpm` | `install`, `run build`, `test`, `run dev` | N/A | +| Xcode | `xcodebuild` | `-project`, `-scheme`, `build`, `test` | N/A | +| Convex | `npx convex` | `dev`, `deploy`, `env set`, `env get` | `npx convex login` | + +### 环境变量自动化 + +**Env 文件：** 使用 write/edit 工具。绝不让用户手动创建 .env。 + +**通过 CLI 的仪表板环境变量：** + +| 平台 | CLI 命令 | 示例 | +|------|----------|------| +| Convex | `npx convex env set` | `npx convex env set OPENAI_API_KEY sk-...` | +| Vercel | `vercel env add` | `vercel env add STRIPE_KEY production` | +| Railway | `railway variables set` | `railway variables set API_KEY=value` | +| Fly | `fly secrets set` | `fly secrets set DATABASE_URL=...` | +| Supabase | `supabase secrets set` | `supabase secrets set MY_SECRET=value` | + +### 开发服务器自动化 + +| 框架 | 启动命令 | 就绪信号 | 默认 URL | +|------|----------|----------|----------| +| Next.js | `npm run dev` | "Ready in" 或 "started server" | http://localhost:3000 | +| Vite | `npm run dev` | "ready in" | http://localhost:5173 | +| Convex | `npx convex dev` | "Convex functions ready" | N/A（仅后端）| +| Express | `npm start` | "listening on port" | http://localhost:3000 | +| Django | `python manage.py runserver` | "Starting development server" | http://localhost:8000 | + +**服务器生命周期：** +```bash +# 后台运行，捕获 PID +npm run dev & +DEV_SERVER_PID=$! + +# 等待就绪（最多 30s） +timeout 30 bash -c 'until curl -s localhost:3000 > /dev/null 2>&1; do sleep 1; done' +``` + +**端口冲突：** 终止陈旧进程（`lsof -ti:3000 | xargs kill`）或使用备用端口（`--port 3001`）。 + +**服务器保持运行** 直到检查点结束。仅在计划完成、切换到生产环境或端口需要用于不同服务时终止。 + +### CLI 安装处理 + +| CLI | 自动安装？ | 命令 | +|-----|------------|------| +| npm/pnpm/yarn | 否 - 询问用户 | 用户选择包管理器 | +| vercel | 是 | `npm i -g vercel` | +| gh (GitHub) | 是 | `brew install gh` (macOS) 或 `apt install gh` (Linux) | +| stripe | 是 | `npm i -g stripe` | +| supabase | 是 | `npm i -g supabase` | +| convex | 否 - 使用 npx | `npx convex`（无需安装）| +| fly | 是 | `brew install flyctl` 或 curl 安装器 | +| railway | 是 | `npm i -g @railway/cli` | + +**协议：** 尝试命令 → "command not found" → 可自动安装？→ 是：静默安装，重试 → 否：检查点请求用户安装。 + +## 检查点前自动化失败处理 + +| 失败 | 响应 | +|------|------| +| 服务器无法启动 | 检查错误，修复问题，重试（不进入检查点）| +| 端口被占用 | 终止陈旧进程或使用备用端口 | +| 缺少依赖 | 运行 `npm install`，重试 | +| 构建错误 | 先修复错误（是 bug，不是检查点问题）| +| 认证错误 | 创建认证门控检查点 | +| 网络超时 | 带退避重试，如果持续则检查点 | + +**绝不呈现验证环境损坏的检查点。** 如果 `curl localhost:3000` 失败，不要让用户"访问 localhost:3000"。 + +## 可自动化快速参考 + +| 操作 | 可自动化？| OpenCode 做？| +|------|------------|------------| +| 部署到 Vercel | 是 (`vercel`) | 是 | +| 创建 Stripe webhook | 是 (API) | 是 | +| 写入 .env 文件 | 是 (write 工具) | 是 | +| 创建 Upstash DB | 是 (`upstash`) | 是 | +| 运行测试 | 是 (`npm test`) | 是 | +| 启动开发服务器 | 是 (`npm run dev`) | 是 | +| 添加环境变量到 Convex | 是 (`npx convex env set`) | 是 | +| 添加环境变量到 Vercel | 是 (`vercel env add`) | 是 | +| 填充数据库 | 是 (CLI/API) | 是 | +| 点击邮件验证链接 | 否 | 否 | +| 输入带 3DS 的信用卡 | 否 | 否 | +| 在浏览器中完成 OAuth | 否 | 否 | +| 视觉验证 UI 是否正确 | 否 | 否 | +| 测试交互式用户流程 | 否 | 否 | + +## 反模式 + +### ❌ 错误：让用户启动开发服务器 +```xml + + 仪表板组件 + + 1. 运行: npm run dev + 2. 访问: http://localhost:3000/dashboard + 3. 检查布局是否正确 + + +``` +**为什么错误：** OpenCode 可以运行 `npm run dev`。用户应该只访问 URL，不执行命令。 + +### ✅ 正确：OpenCode 启动服务器，用户访问 +```xml + + 启动开发服务器 + 在后台运行 `npm run dev` + curl localhost:3000 返回 200 + + + + http://localhost:3000/dashboard 的仪表板（服务器运行中） + + 访问 http://localhost:3000/dashboard 并验证： + 1. 布局匹配设计 + 2. 无控制台错误 + + +``` + +### ❌ 错误：让用户部署 / ✅ 正确：OpenCode 自动化 +```xml + + + 部署到 Vercel + 访问 vercel.com/new → 导入仓库 → 点击部署 → 复制 URL + + + + + 部署到 Vercel + 运行 `vercel --yes`。捕获 URL。 + vercel ls 显示部署，curl 返回 200 + + + + 已部署到 {url} + 访问 {url}，检查首页加载 + 输入 "approved" + +``` + +## 摘要 + +检查点规范化人工介入点用于验证和决策，而非手动工作。 + +**黄金法则：** 如果 OpenCode 能自动化它，OpenCode 就必须自动化它。 + +**检查点优先级：** +1. **checkpoint:human-verify**（90%）- OpenCode 自动化一切，人工确认视觉/功能正确性 +2. **checkpoint:decision**（9%）- 人工做出架构/技术选择 +3. **checkpoint:human-action**（1%）- 真正无法避免的、没有 API/CLI 的手动步骤 + +**何时不用检查点：** +- OpenCode 可以编程验证的事情（测试、构建） +- 文件操作（OpenCode 可以读取文件） +- 代码正确性（测试和静态分析） +- 任何可通过 CLI/API 自动化的内容 \ No newline at end of file diff --git a/gsd-opencode/docs/zh-CN/references/continuation-format.md b/gsd-opencode/docs/zh-CN/references/continuation-format.md new file mode 100644 index 0000000..f46dbc3 --- /dev/null +++ b/gsd-opencode/docs/zh-CN/references/continuation-format.md @@ -0,0 +1,249 @@ +# 续接格式 + +完成命令或工作流后展示下一步的标准格式。 + +## 核心结构 + +``` +--- + +## ▶ 下一步 + +**{标识符}: {名称}** — {单行描述} + +`{可复制粘贴的命令}` + +*`/new` 优先 → 全新上下文窗口* + +--- + +**也可选：** +- `{备选项 1}` — 描述 +- `{备选项 2}` — 描述 + +--- +``` + +## 格式规则 + +1. **始终展示它是什么** — 名称 + 描述，绝不仅仅是一个命令路径 +2. **从源文件拉取上下文** — ROADMAP.md 用于阶段，PLAN.md `` 用于计划 +3. **命令用内联代码** — 反引号，易于复制粘贴，渲染为可点击链接 +4. **`/new` 说明** — 始终包含，保持简洁但解释原因 +5. **用"也可选"而非"其他选项"** — 听起来更像应用 +6. **视觉分隔符** — 上下用 `---` 使其突出 + +## 变体 + +### 执行下一个计划 + +``` +--- + +## ▶ 下一步 + +**02-03: 刷新令牌轮换** — 添加带滑动过期的 /api/auth/refresh + +`/gsd-execute-phase 2` + +*`/new` 优先 → 全新上下文窗口* + +--- + +**也可选：** +- 执行前审查计划 +- `/gsd-list-phase-assumptions 2` — 检查假设 + +--- +``` + +### 执行阶段中最后一个计划 + +添加注释说明这是最后一个计划以及接下来是什么： + +``` +--- + +## ▶ 下一步 + +**02-03: 刷新令牌轮换** — 添加带滑动过期的 /api/auth/refresh +*阶段 2 的最后一个计划* + +`/gsd-execute-phase 2` + +*`/new` 优先 → 全新上下文窗口* + +--- + +**完成后：** +- 阶段 2 → 阶段 3 过渡 +- 下一步：**阶段 3: 核心功能** — 用户仪表板和设置 + +--- +``` + +### 规划阶段 + +``` +--- + +## ▶ 下一步 + +**阶段 2: 认证** — 带刷新令牌的 JWT 登录流程 + +`/gsd-plan-phase 2` + +*`/new` 优先 → 全新上下文窗口* + +--- + +**也可选：** +- `/gsd-discuss-phase 2` — 先收集上下文 +- `/gsd-research-phase 2` — 调查未知项 +- 审查路线图 + +--- +``` + +### 阶段完成，准备下一步 + +在下一步操作前显示完成状态： + +``` +--- + +## ✓ 阶段 2 完成 + +3/3 计划已执行 + +## ▶ 下一步 + +**阶段 3: 核心功能** — 用户仪表板、设置和数据导出 + +`/gsd-plan-phase 3` + +*`/new` 优先 → 全新上下文窗口* + +--- + +**也可选：** +- `/gsd-discuss-phase 3` — 先收集上下文 +- `/gsd-research-phase 3` — 调查未知项 +- 回顾阶段 2 构建的内容 + +--- +``` + +### 多个同等选项 + +当没有明确的主要操作时： + +``` +--- + +## ▶ 下一步 + +**阶段 3: 核心功能** — 用户仪表板、设置和数据导出 + +**直接规划：** `/gsd-plan-phase 3` + +**先讨论上下文：** `/gsd-discuss-phase 3` + +**研究未知项：** `/gsd-research-phase 3` + +*`/new` 优先 → 全新上下文窗口* + +--- +``` + +### 里程碑完成 + +``` +--- + +## 🎉 里程碑 v1.0 完成 + +全部 4 个阶段已发布 + +## ▶ 下一步 + +**开始 v1.1** — 提问 → 研究 → 需求 → 路线图 + +`/gsd-new-milestone` + +*`/new` 优先 → 全新上下文窗口* + +--- +``` + +## 拉取上下文 + +### 用于阶段（从 ROADMAP.md）： + +```markdown +### 阶段 2: 认证 +**目标**: 带刷新令牌的 JWT 登录流程 +``` + +提取：`**阶段 2: 认证** — 带刷新令牌的 JWT 登录流程` + +### 用于计划（从 ROADMAP.md）： + +```markdown +计划: +- [ ] 02-03: 添加刷新令牌轮换 +``` + +或从 PLAN.md ``： + +```xml + +添加带滑动过期窗口的刷新令牌轮换。 + +目的: 在不影响安全性的前提下延长会话生命周期。 + +``` + +提取：`**02-03: 刷新令牌轮换** — 添加带滑动过期的 /api/auth/refresh` + +## 反模式 + +### 不要：仅命令（无上下文） + +``` +## 继续 + +运行 `/new`，然后粘贴： +/gsd-execute-phase 2 +``` + +用户不知道 02-03 是关于什么的。 + +### 不要：缺少 /new 说明 + +``` +`/gsd-plan-phase 3` + +先运行 /new。 +``` + +没有解释原因。用户可能跳过。 + +### 不要："其他选项" 措辞 + +``` +其他选项： +- 审查路线图 +``` + +听起来像是事后补充。用"也可选："替代。 + +### 不要：用围栏代码块展示命令 + +``` +``` +/gsd-plan-phase 3 +``` +``` + +模板内的围栏代码块会造成嵌套歧义。用内联反引号替代。 \ No newline at end of file diff --git a/gsd-opencode/docs/zh-CN/references/decimal-phase-calculation.md b/gsd-opencode/docs/zh-CN/references/decimal-phase-calculation.md new file mode 100644 index 0000000..d3bc38b --- /dev/null +++ b/gsd-opencode/docs/zh-CN/references/decimal-phase-calculation.md @@ -0,0 +1,65 @@ +# 小数阶段计算 + +为紧急插入计算下一个小数阶段编号。 + +## 使用 gsd-tools + +```bash +# 获取阶段 6 之后的下一个小数阶段 +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" phase next-decimal 6 +``` + +输出： +```json +{ + "found": true, + "base_phase": "06", + "next": "06.1", + "existing": [] +} +``` + +已有小数时： +```json +{ + "found": true, + "base_phase": "06", + "next": "06.3", + "existing": ["06.1", "06.2"] +} +``` + +## 提取值 + +```bash +DECIMAL_INFO=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" phase next-decimal "${AFTER_PHASE}") +DECIMAL_PHASE=$(printf '%s\n' "$DECIMAL_INFO" | jq -r '.next') +BASE_PHASE=$(printf '%s\n' "$DECIMAL_INFO" | jq -r '.base_phase') +``` + +或使用 --raw 标志： +```bash +DECIMAL_PHASE=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" phase next-decimal "${AFTER_PHASE}" --raw) +# 返回: 06.1 +``` + +## 示例 + +| 已有阶段 | 下一个阶段 | +|----------|------------| +| 仅 06 | 06.1 | +| 06, 06.1 | 06.2 | +| 06, 06.1, 06.2 | 06.3 | +| 06, 06.1, 06.3（有空缺）| 06.4 | + +## 目录命名 + +小数阶段目录使用完整的小数编号： + +```bash +SLUG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" generate-slug "$DESCRIPTION" --raw) +PHASE_DIR=".planning/phases/${DECIMAL_PHASE}-${SLUG}" +mkdir -p "$PHASE_DIR" +``` + +示例：`.planning/phases/06.1-fix-critical-auth-bug/` \ No newline at end of file diff --git a/gsd-opencode/docs/zh-CN/references/git-integration.md b/gsd-opencode/docs/zh-CN/references/git-integration.md new file mode 100644 index 0000000..db48bd4 --- /dev/null +++ b/gsd-opencode/docs/zh-CN/references/git-integration.md @@ -0,0 +1,248 @@ + +GSD 框架的 Git 集成。 + + + + +**提交结果，而非过程。** + +git 日志应该读起来像是发布内容的变更日志，而不是规划活动的日记。 + + + + +| 事件 | 提交? | 原因 | +| ----------------------- | ------- | ------------------------------------------------ | +| BRIEF + ROADMAP 创建 | 是 | 项目初始化 | +| PLAN.md 创建 | 否 | 中间产物 - 与计划完成一起提交 | +| RESEARCH.md 创建 | 否 | 中间产物 | +| DISCOVERY.md 创建 | 否 | 中间产物 | +| **任务完成** | 是 | 原子工作单元（每个任务 1 个提交） | +| **计划完成** | 是 | 元数据提交（SUMMARY + STATE + ROADMAP） | +| 交接创建 | 是 | WIP 状态保留 | + + + + + +```bash +[ -d .git ] && echo "GIT_EXISTS" || echo "NO_GIT" +``` + +如果 NO_GIT：静默运行 `git init`。GSD 项目总是有自己的仓库。 + + + + + +## 项目初始化（brief + roadmap 一起） + +``` +docs: initialize [project-name] ([N] phases) + +[PROJECT.md 中的一句话描述] + +Phases: +1. [phase-name]: [goal] +2. [phase-name]: [goal] +3. [phase-name]: [goal] +``` + +提交内容： + +```bash +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: initialize [project-name] ([N] phases)" --files .planning/ +``` + + + + +## 任务完成（计划执行期间） + +每个任务在完成后立即获得自己的提交。 + +``` +{type}({phase}-{plan}): {task-name} + +- [关键变更 1] +- [关键变更 2] +- [关键变更 3] +``` + +**提交类型：** +- `feat` - 新功能/功能 +- `fix` - Bug 修复 +- `test` - 仅测试（TDD RED 阶段） +- `refactor` - 代码清理（TDD REFACTOR 阶段） +- `perf` - 性能改进 +- `chore` - 依赖、配置、工具 + +**示例：** + +```bash +# 标准任务 +git add src/api/auth.ts src/types/user.ts +git commit -m "feat(08-02): create user registration endpoint + +- POST /auth/register validates email and password +- Checks for duplicate users +- Returns JWT token on success +" + +# TDD 任务 - RED 阶段 +git add src/__tests__/jwt.test.ts +git commit -m "test(07-02): add failing test for JWT generation + +- Tests token contains user ID claim +- Tests token expires in 1 hour +- Tests signature verification +" + +# TDD 任务 - GREEN 阶段 +git add src/utils/jwt.ts +git commit -m "feat(07-02): implement JWT generation + +- Uses jose library for signing +- Includes user ID and expiry claims +- Signs with HS256 algorithm +" +``` + + + + +## 计划完成（所有任务完成后） + +所有任务提交后，最后一个元数据提交捕获计划完成。 + +``` +docs({phase}-{plan}): complete [plan-name] plan + +Tasks completed: [N]/[N] +- [task 1 name] +- [task 2 name] +- [task 3 name] + +SUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md +``` + +提交内容： + +```bash +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md +``` + +**注意：** 代码文件不包含 - 已按任务提交。 + + + + +## 交接（WIP） + +``` +wip: [phase-name] paused at task [X]/[Y] + +Current: [task name] +[如果阻塞:] Blocked: [reason] +``` + +提交内容： + +```bash +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/ +``` + + + + + + +**旧方法（每个计划提交）：** +``` +a7f2d1 feat(checkout): Stripe payments with webhook verification +3e9c4b feat(products): catalog with search, filters, and pagination +8a1b2c feat(auth): JWT with refresh rotation using jose +5c3d7e feat(foundation): Next.js 15 + Prisma + Tailwind scaffold +2f4a8d docs: initialize ecommerce-app (5 phases) +``` + +**新方法（每个任务提交）：** +``` +# Phase 04 - Checkout +1a2b3c docs(04-01): complete checkout flow plan +4d5e6f feat(04-01): add webhook signature verification +7g8h9i feat(04-01): implement payment session creation +0j1k2l feat(04-01): create checkout page component + +# Phase 03 - Products +3m4n5o docs(03-02): complete product listing plan +6p7q8r feat(03-02): add pagination controls +9s0t1u feat(03-02): implement search and filters +2v3w4x feat(03-01): create product catalog schema + +# Phase 02 - Auth +5y6z7a docs(02-02): complete token refresh plan +8b9c0d feat(02-02): implement refresh token rotation +1e2f3g test(02-02): add failing test for token refresh +4h5i6j docs(02-01): complete JWT setup plan +7k8l9m feat(02-01): add JWT generation and validation +0n1o2p chore(02-01): install jose library + +# Phase 01 - Foundation +3q4r5s docs(01-01): complete scaffold plan +6t7u8v feat(01-01): configure Tailwind and globals +9w0x1y feat(01-01): set up Prisma with database +2z3a4b feat(01-01): create Next.js 15 project + +# Initialization +5c6d7e docs: initialize ecommerce-app (5 phases) +``` + +每个计划产生 2-4 个提交（任务 + 元数据）。清晰、细粒度、可 bisect。 + + + + + +**仍不要提交（中间产物）：** +- PLAN.md 创建（与计划完成一起提交） +- RESEARCH.md（中间产物） +- DISCOVERY.md（中间产物） +- 小的规划调整 +- "Fixed typo in roadmap" + +**要提交（结果）：** +- 每个任务完成（feat/fix/test/refactor） +- 计划完成元数据（docs） +- 项目初始化（docs） + +**关键原则：** 提交可工作的代码和已发布的结果，而非规划过程。 + + + + + +## 为什么使用每任务提交？ + +**AI 上下文工程：** +- Git 历史成为未来 OpenCode 会话的主要上下文源 +- `git log --grep="{phase}-{plan}"` 显示计划的所有工作 +- `git diff ^..` 显示每个任务的确切变更 +- 减少对解析 SUMMARY.md 的依赖 = 更多上下文用于实际工作 + +**失败恢复：** +- 任务 1 已提交 ✅，任务 2 失败 ❌ +- 下次会话中的 OpenCode：看到任务 1 完成，可以重试任务 2 +- 可以 `git reset --hard` 到最后一个成功的任务 + +**调试：** +- `git bisect` 找到确切的失败任务，而不仅仅是失败计划 +- `git blame` 将行追溯到特定任务上下文 +- 每个提交独立可回滚 + +**可观察性：** +- 独立开发者 + OpenCode 工作流受益于细粒度归因 +- 原子提交是 git 最佳实践 +- 当消费者是 OpenCode 而非人类时，"提交噪音"无关紧要 + + \ No newline at end of file diff --git a/gsd-opencode/docs/zh-CN/references/git-planning-commit.md b/gsd-opencode/docs/zh-CN/references/git-planning-commit.md new file mode 100644 index 0000000..299c1a5 --- /dev/null +++ b/gsd-opencode/docs/zh-CN/references/git-planning-commit.md @@ -0,0 +1,38 @@ +# Git 规划提交 + +使用 gsd-tools CLI 提交规划工件，它会自动检查 `commit_docs` 配置和 gitignore 状态。 + +## 通过 CLI 提交 + +始终使用 `gsd-tools.cjs commit` 处理 `.planning/` 文件 — 它会自动处理 `commit_docs` 和 gitignore 检查： + +```bash +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md +``` + +如果 `commit_docs` 为 `false` 或 `.planning/` 被 gitignore，CLI 会返回 `skipped`（带原因）。无需手动条件检查。 + +## 修改上次提交 + +将 `.planning/` 文件变更合并到上次提交： + +```bash +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "" --files .planning/codebase/*.md --amend +``` + +## 提交消息模式 + +| 命令 | 范围 | 示例 | +|------|------|------| +| plan-phase | phase | `docs(phase-03): create authentication plans` | +| execute-phase | phase | `docs(phase-03): complete authentication phase` | +| new-milestone | milestone | `docs: start milestone v1.1` | +| remove-phase | chore | `chore: remove phase 17 (dashboard)` | +| insert-phase | phase | `docs: insert phase 16.1 (critical fix)` | +| add-phase | phase | `docs: add phase 07 (settings page)` | + +## 何时跳过 + +- config 中 `commit_docs: false` +- `.planning/` 被 gitignore +- 无变更可提交（用 `git status --porcelain .planning/` 检查） \ No newline at end of file diff --git a/gsd-opencode/docs/zh-CN/references/model-profile-resolution.md b/gsd-opencode/docs/zh-CN/references/model-profile-resolution.md new file mode 100644 index 0000000..db1e579 --- /dev/null +++ b/gsd-opencode/docs/zh-CN/references/model-profile-resolution.md @@ -0,0 +1,34 @@ +# 模型配置解析 + +在编排开始时解析一次模型配置，然后在所有 task 生成时使用。 + +## 解析模式 + +```bash +MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced") +``` + +默认值：未设置或缺少 config 时为 `balanced`。 + +## 查找表 + +@$HOME/.config/opencode/get-shit-done/references/model-profiles.md + +在表中查找已解析配置对应的代理。将 model 参数传递给 task 调用： + +``` +task( + prompt="...", + subagent_type="gsd-planner", + model="{resolved_model}" # "inherit"、"sonnet" 或 "haiku" +) +``` + +**注意：** Opus 级代理解析为 `"inherit"`（而非 `"opus"`）。这会使代理使用父会话的模型，避免与可能阻止特定 opus 版本的组织策略冲突。 + +## 使用方法 + +1. 在编排开始时解析一次 +2. 存储 profile 值 +3. 生成时在表中查找每个代理的模型 +4. 将 model 参数传递给每个 task 调用（值：`"inherit"`、`"sonnet"`、`"haiku"`） \ No newline at end of file diff --git a/gsd-opencode/docs/zh-CN/references/model-profiles.md b/gsd-opencode/docs/zh-CN/references/model-profiles.md new file mode 100644 index 0000000..6ba75ef --- /dev/null +++ b/gsd-opencode/docs/zh-CN/references/model-profiles.md @@ -0,0 +1,93 @@ +# 模型配置 + +模型配置控制每个 GSD 代理使用哪个 OpenCode 模型。这允许平衡质量和 token 消耗。 + +## 配置定义 + +| 代理 | `quality` | `balanced` | `budget` | +|-------|-----------|------------|----------| +| gsd-planner | opus | opus | sonnet | +| gsd-roadmapper | opus | sonnet | sonnet | +| gsd-executor | opus | sonnet | sonnet | +| gsd-phase-researcher | opus | sonnet | haiku | +| gsd-project-researcher | opus | sonnet | haiku | +| gsd-research-synthesizer | sonnet | sonnet | haiku | +| gsd-debugger | opus | sonnet | sonnet | +| gsd-codebase-mapper | sonnet | haiku | haiku | +| gsd-verifier | sonnet | sonnet | haiku | +| gsd-plan-checker | sonnet | sonnet | haiku | +| gsd-integration-checker | sonnet | sonnet | haiku | +| gsd-nyquist-auditor | sonnet | sonnet | haiku | + +## 配置理念 + +**quality** - 最大推理能力 +- 所有决策代理使用 Opus +- 只读验证使用 Sonnet +- 适用场景：有配额可用、关键架构工作 + +**balanced**（默认）- 智能分配 +- 仅规划（架构决策发生的地方）使用 Opus +- 执行和研究使用 Sonnet（遵循明确指令） +- 验证使用 Sonnet（需要推理，不仅仅是模式匹配） +- 适用场景：正常开发、质量与成本的良好平衡 + +**budget** - 最小化 Opus 使用 +- 编写代码的使用 Sonnet +- 研究和验证使用 Haiku +- 适用场景：节省配额、大量工作、不太关键的阶段 + +## 解析逻辑 + +编排器在生成代理前解析模型： + +``` +1. 读取 .planning/config.json +2. 检查 model_overrides 是否有代理特定覆盖 +3. 如果没有覆盖，在配置表中查找代理 +4. 将 model 参数传递给 task 调用 +``` + +## 单代理覆盖 + +覆盖特定代理而不更改整个配置： + +```json +{ + "model_profile": "balanced", + "model_overrides": { + "gsd-executor": "opus", + "gsd-planner": "haiku" + } +} +``` + +覆盖优先于配置。有效值：`opus`、`sonnet`、`haiku`。 + +## 切换配置 + +运行时：`/gsd-set-profile ` + +项目默认值：在 `.planning/config.json` 中设置： +```json +{ + "model_profile": "balanced" +} +``` + +## 设计理由 + +**为什么 gsd-planner 使用 Opus？** +规划涉及架构决策、目标分解和任务设计。这是模型质量影响最大的地方。 + +**为什么 gsd-executor 使用 Sonnet？** +执行者遵循明确的 PLAN.md 指令。计划已包含推理；执行只是实现。 + +**为什么 balanced 中验证器使用 Sonnet（而非 Haiku）？** +验证需要目标回溯推理 —— 检查代码是否**交付**了阶段承诺的内容，而不仅仅是模式匹配。Sonnet 处理得很好；Haiku 可能会遗漏细微的差距。 + +**为什么 gsd-codebase-mapper 使用 Haiku？** +只读探索和模式提取。不需要推理，只需从文件内容输出结构化结果。 + +**为什么用 `inherit` 而不是直接传递 `opus`？** +OpenCode 的 `"opus"` 别名映射到特定模型版本。组织可能阻止旧版 opus 而允许新版。GSD 为 opus 级代理返回 `"inherit"`，使其使用用户在会话中配置的任何 opus 版本。这避免了版本冲突和静默回退到 Sonnet。 \ No newline at end of file diff --git a/gsd-opencode/docs/zh-CN/references/phase-argument-parsing.md b/gsd-opencode/docs/zh-CN/references/phase-argument-parsing.md new file mode 100644 index 0000000..6f20402 --- /dev/null +++ b/gsd-opencode/docs/zh-CN/references/phase-argument-parsing.md @@ -0,0 +1,61 @@ +# 阶段参数解析 + +为操作阶段的命令解析和规范化阶段参数。 + +## 提取 + +从 `$ARGUMENTS` 中： +- 提取阶段编号（第一个数字参数） +- 提取标志（以 `--` 为前缀） +- 剩余文本为描述（用于 insert/add 命令） + +## 使用 gsd-tools + +`find-phase` 命令一步完成规范化和验证： + +```bash +PHASE_INFO=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" find-phase "${PHASE}") +``` + +返回 JSON 包含： +- `found`: true/false +- `directory`: 阶段目录的完整路径 +- `phase_number`: 规范化的编号（如 "06"、"06.1"） +- `phase_name`: 名称部分（如 "foundation"） +- `plans`: PLAN.md 文件数组 +- `summaries`: SUMMARY.md 文件数组 + +## 手动规范化（遗留） + +将整数阶段补零到 2 位。保留小数后缀。 + +```bash +# 规范化阶段编号 +if [[ "$PHASE" =~ ^[0-9]+$ ]]; then + # 整数: 8 → 08 + PHASE=$(printf "%02d" "$PHASE") +elif [[ "$PHASE" =~ ^([0-9]+)\.([0-9]+)$ ]]; then + # 小数: 2.1 → 02.1 + PHASE=$(printf "%02d.%s" "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}") +fi +``` + +## 验证 + +使用 `roadmap get-phase` 验证阶段存在： + +```bash +PHASE_CHECK=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "${PHASE}") +if [ "$(printf '%s\n' "$PHASE_CHECK" | jq -r '.found')" = "false" ]; then + echo "ERROR: Phase ${PHASE} not found in roadmap" + exit 1 +fi +``` + +## 目录查找 + +使用 `find-phase` 进行目录查找： + +```bash +PHASE_DIR=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" find-phase "${PHASE}" --raw) +``` \ No newline at end of file diff --git a/gsd-opencode/docs/zh-CN/references/planning-config.md b/gsd-opencode/docs/zh-CN/references/planning-config.md new file mode 100644 index 0000000..22d0a6d --- /dev/null +++ b/gsd-opencode/docs/zh-CN/references/planning-config.md @@ -0,0 +1,200 @@ + + +`.planning/` 目录行为的配置选项。 + + +```json +"planning": { + "commit_docs": true, + "search_gitignored": false +}, +"git": { + "branching_strategy": "none", + "phase_branch_template": "gsd/phase-{phase}-{slug}", + "milestone_branch_template": "gsd/{milestone}-{slug}" +} +``` + +| 选项 | 默认值 | 描述 | +|--------|---------|-------------| +| `commit_docs` | `true` | 是否将规划工件提交到 git | +| `search_gitignored` | `false` | 在广泛 rg 搜索中添加 `--no-ignore` | +| `git.branching_strategy` | `"none"` | Git 分支策略：`"none"`、`"phase"` 或 `"milestone"` | +| `git.phase_branch_template` | `"gsd/phase-{phase}-{slug}"` | 阶段策略的分支模板 | +| `git.milestone_branch_template` | `"gsd/{milestone}-{slug}"` | 里程碑策略的分支模板 | + + + + +**当 `commit_docs: true`（默认）：** +- 规划文件正常提交 +- SUMMARY.md、STATE.md、ROADMAP.md 在 git 中跟踪 +- 规划决策的完整历史保留 + +**当 `commit_docs: false`：** +- 跳过 `.planning/` 文件的所有 `git add`/`git commit` +- 用户必须将 `.planning/` 添加到 `.gitignore` +- 适用于：OSS 贡献、客户项目、保持规划私有 + +**使用 gsd-tools.cjs（推荐）：** + +```bash +# 提交时自动检查 commit_docs + gitignore： +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: update state" --files .planning/STATE.md + +# 通过 state load 加载配置（返回 JSON）： +INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" state load) +if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +# commit_docs 在 JSON 输出中可用 + +# 或使用包含 commit_docs 的 init 命令： +INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init execute-phase "1") +if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +# commit_docs 包含在所有 init 命令输出中 +``` + +**自动检测：** 如果 `.planning/` 被 gitignore，无论 config.json 如何，`commit_docs` 自动为 `false`。这防止用户在 `.gitignore` 中有 `.planning/` 时出现 git 错误。 + +**通过 CLI 提交（自动处理检查）：** + +```bash +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: update state" --files .planning/STATE.md +``` + +CLI 在内部检查 `commit_docs` 配置和 gitignore 状态 —— 无需手动条件判断。 + + + + + +**当 `search_gitignored: false`（默认）：** +- 标准 rg 行为（尊重 .gitignore） +- 直接路径搜索有效：`rg "pattern" .planning/` 找到文件 +- 广泛搜索跳过 gitignored：`rg "pattern"` 跳过 `.planning/` + +**当 `search_gitignored: true`:** +- 在应该包含 `.planning/` 的广泛 rg 搜索中添加 `--no-ignore` +- 仅在搜索整个仓库并期望 `.planning/` 匹配时需要 + +**注意：** 大多数 GSD 操作使用直接文件读取或显式路径，无论 gitignore 状态如何都有效。 + + + + + +使用未提交模式： + +1. **设置配置：** + ```json + "planning": { + "commit_docs": false, + "search_gitignored": true + } + ``` + +2. **添加到 .gitignore：** + ``` + .planning/ + ``` + +3. **已存在的跟踪文件：** 如果 `.planning/` 之前被跟踪： + ```bash + git rm -r --cached .planning/ + git commit -m "chore: stop tracking planning docs" + ``` + +4. **分支合并：** 当使用 `branching_strategy: phase` 或 `milestone` 时，`complete-milestone` 工作流在 `commit_docs: false` 时自动从暂存区移除 `.planning/` 文件，然后才进行合并提交。 + + + + + +**分支策略：** + +| 策略 | 创建分支时机 | 分支范围 | 合并点 | +|----------|---------------------|--------------|-------------| +| `none` | 从不 | N/A | N/A | +| `phase` | `execute-phase` 开始时 | 单个阶段 | 阶段后用户手动合并 | +| `milestone` | 里程碑第一个 `execute-phase` | 整个里程碑 | `complete-milestone` 时 | + +**当 `git.branching_strategy: "none"`（默认）：** +- 所有工作提交到当前分支 +- 标准 GSD 行为 + +**当 `git.branching_strategy: "phase"`：** +- `execute-phase` 在执行前创建/切换到分支 +- 分支名来自 `phase_branch_template`（如 `gsd/phase-03-authentication`） +- 所有计划提交到该分支 +- 阶段完成后用户手动合并分支 +- `complete-milestone` 提供合并所有阶段分支的选项 + +**当 `git.branching_strategy: "milestone"`：** +- 里程碑的第一个 `execute-phase` 创建里程碑分支 +- 分支名来自 `milestone_branch_template`（如 `gsd/v1.0-mvp`） +- 里程碑中所有阶段提交到同一分支 +- `complete-milestone` 提供将里程碑分支合并到 main 的选项 + +**模板变量：** + +| 变量 | 可用于 | 描述 | +|----------|--------------|-------------| +| `{phase}` | phase_branch_template | 零填充阶段号（如 "03"） | +| `{slug}` | 两者 | 小写、连字符名称 | +| `{milestone}` | milestone_branch_template | 里程碑版本（如 "v1.0"） | + +**检查配置：** + +使用 `init execute-phase` 返回所有配置为 JSON： +```bash +INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init execute-phase "1") +if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +# JSON 输出包含：branching_strategy, phase_branch_template, milestone_branch_template +``` + +或使用 `state load` 获取配置值： +```bash +INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" state load) +if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +# 从 JSON 解析 branching_strategy, phase_branch_template, milestone_branch_template +``` + +**分支创建：** + +```bash +# 阶段策略 +if [ "$BRANCHING_STRATEGY" = "phase" ]; then + PHASE_SLUG=$(echo "$PHASE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//') + BRANCH_NAME=$(echo "$PHASE_BRANCH_TEMPLATE" | sed "s/{phase}/$PADDED_PHASE/g" | sed "s/{slug}/$PHASE_SLUG/g") + git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME" +fi + +# 里程碑策略 +if [ "$BRANCHING_STRATEGY" = "milestone" ]; then + MILESTONE_SLUG=$(echo "$MILESTONE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//') + BRANCH_NAME=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed "s/{milestone}/$MILESTONE_VERSION/g" | sed "s/{slug}/$MILESTONE_SLUG/g") + git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME" +fi +``` + +**complete-milestone 时的合并选项：** + +| 选项 | Git 命令 | 结果 | +|--------|-------------|--------| +| Squash 合并（推荐） | `git merge --squash` | 每个分支单个干净提交 | +| 带历史合并 | `git merge --no-ff` | 保留所有单独提交 | +| 不合并直接删除 | `git branch -D` | 丢弃分支工作 | +| 保留分支 | （无） | 后续手动处理 | + +推荐 Squash 合并 —— 保持 main 分支历史干净，同时在分支中保留完整开发历史（直到删除）。 + +**使用场景：** + +| 策略 | 最适合 | +|----------|----------| +| `none` | 独立开发、简单项目 | +| `phase` | 每阶段代码审查、细粒度回滚、团队协作 | +| `milestone` | 发布分支、预发布环境、每个版本一个 PR | + + + + \ No newline at end of file diff --git a/gsd-opencode/docs/zh-CN/references/questioning.md b/gsd-opencode/docs/zh-CN/references/questioning.md new file mode 100644 index 0000000..8090440 --- /dev/null +++ b/gsd-opencode/docs/zh-CN/references/questioning.md @@ -0,0 +1,142 @@ +# 提问指南 + +项目初始化是梦想提取，而非需求收集。你在帮助用户发现和表达他们想构建的内容。这不是合同谈判 —— 是协作思考。 + +## 理念 + +**你是思考伙伴，不是面试官。** + +用户通常有一个模糊的想法。你的工作是帮助他们将其锐化。问一些让他们思考"哦，我没想到那个"或"是的，这正是我的意思"的问题。 + +不要审问。协作。不要照本宣科。顺藤摸瓜。 + +## 目标 + +到提问结束时，你需要足够的清晰度来编写下游阶段可执行的 PROJECT.md： + +- **研究** 需要：研究什么领域、用户已知什么、存在哪些未知 +- **需求** 需要：足够清晰的愿景来界定 v1 功能 +- **路线图** 需要：足够清晰的愿景来分解为阶段、"完成"是什么样子 +- **plan-phase** 需要：可分解为任务的具体需求、实现选择的上下文 +- **execute-phase** 需要：可验证的成功标准、需求背后的"为什么" + +模糊的 PROJECT.md 会让每个下游阶段都在猜测。成本会叠加。 + +## 如何提问 + +**开放开始。** 让他们倾倒心理模型。不要用结构打断。 + +**跟随能量。** 无论他们强调什么，深入那个。什么让他们兴奋？什么问题引发了这一切？ + +**挑战模糊。** 绝不接受模糊回答。"好"意味着什么？"用户"指谁？"简单"是怎么简单？ + +**让抽象具体。**"带我走一遍使用这个。""那实际看起来是什么样？" + +**澄清歧义。**"你说 Z 时，是指 A 还是 B？""你提到了 X —— 跟我多说说。" + +**知道何时停止。** 当你理解他们想要什么、为什么想要、给谁用、完成是什么样 —— 提议继续。 + +## 问题类型 + +以此作为灵感，不是清单。选择与话题相关的。 + +**动机 —— 为什么存在：** +- "什么引发了这一切？" +- "你今天在做什么会被这个替代？" +- "如果这个存在，你会做什么？" + +**具体性 —— 它实际是什么：** +- "带我走一遍使用这个" +- "你说 X —— 那实际看起来是什么样？" +- "给我一个例子" + +**澄清 —— 他们什么意思：** +- "你说 Z 时，是指 A 还是 B？" +- "你提到了 X —— 跟我多说说那个" + +**成功 —— 你怎么知道它在工作：** +- "你怎么知道这个在工作？" +- "完成是什么样子？" + +## 使用 question + +用 question 帮助用户思考，通过呈现具体的选项供他们反应。 + +**好选项：** +- 他们可能意思的解读 +- 确认或否认的具体例子 +- 揭示优先级的具体选择 + +**坏选项：** +- 泛泛的类别（"技术"、"业务"、"其他"） +- 预设答案的引导性选项 +- 选项太多（2-4 个理想） +- 超过 12 个字符的标题（硬限制 —— 验证会拒绝） + +**示例 —— 模糊回答：** +用户说"它应该快" + +- header: "快" +- question: "快是指？" +- options: ["亚秒响应", "处理大数据集", "快速构建", "让我解释"] + +**示例 —— 跟随话题：** +用户提到"对当前工具感到沮丧" + +- header: "沮丧" +- question: "具体什么让你沮丧？" +- options: ["点击太多", "缺少功能", "不可靠", "让我解释"] + +**给用户的提示 —— 修改选项：** +想要稍微修改某个选项版本的用户可以选择"Other"并通过编号引用选项：`#1 但仅用于指关节` 或 `#2 禁用分页`。这避免重新输入完整选项文本。 + +## 自由格式规则 + +**当用户想自由解释时，停止使用 question。** + +如果用户选择"Other"且他们的回应表明他们想用自己的话描述（如"让我描述一下"、"我来解释"、"别的"、或任何非选择/修改现有选项的开放式回复），你必须： + +1. **用纯文本问你的追问** — 不通过 question +2. **等待他们在正常提示符下输入** +3. **仅在处理他们的自由格式回应后恢复 question** + +同样适用于如果你包含一个表明自由格式的选项（如"让我解释"或"详细描述"）且用户选择了它。 + +**错误：** 用户说"让我描述一下" → question("什么功能？", ["功能 A", "功能 B", "详细描述"]) +**正确：** 用户说"让我描述一下" → "请讲 —— 你在想什么？" + +## 上下文清单 + +以此作为**背景清单**，而非对话结构。进行时在脑中检查这些。如果还有缺口，自然地穿插问题。 + +- [ ] 他们在构建什么（足够具体可以向陌生人解释） +- [ ] 为什么它需要存在（驱动它的问题或渴望） +- [ ] 给谁用的（即使只是他们自己） +- [ ] "完成"是什么样子（可观察的结果） + +四件事。如果他们主动提供更多，捕获它。 + +## 决策门控 + +当你能写出清晰的 PROJECT.md 时，提议继续： + +- header: "准备好了？" +- question: "我想我理解你想要什么了。准备创建 PROJECT.md 吗？" +- options: + - "创建 PROJECT.md" — 让我们继续 + - "继续探索" — 我想分享更多 / 再问我 + +如果"继续探索" —— 问他们想添加什么或识别缺口并自然探查。 + +循环直到选择"创建 PROJECT.md"。 + +## 反模式 + +- **走清单** — 不管他们说什么都按领域走 +- **套话问题** — "你的核心价值是什么？""什么超出范围？"不管上下文 +- **企业腔** — "你的成功标准是什么？""你的利益相关者是谁？" +- **审问** — 不基于回答构建就连续发问 +- **急于求成** — 最小化问题以开始"实际工作" +- **浅层接受** — 不探查就接受模糊回答 +- **过早约束** — 还不理解想法就问技术栈 +- **用户技能** — 绝不问用户的技术经验。OpenCode 来构建。 \ No newline at end of file diff --git a/gsd-opencode/docs/zh-CN/references/tdd.md b/gsd-opencode/docs/zh-CN/references/tdd.md new file mode 100644 index 0000000..247bf77 --- /dev/null +++ b/gsd-opencode/docs/zh-CN/references/tdd.md @@ -0,0 +1,263 @@ + +TDD 关乎设计质量，而非覆盖率指标。红-绿-重构循环迫使你在实现前思考行为，从而产生更清晰的接口和更可测试的代码。 + +**原则：** 如果在编写 `fn` 之前能用 `expect(fn(input)).toBe(output)` 描述行为，TDD 会改善结果。 + +**关键洞察：** TDD 工作本质上比标准任务更重 —— 它需要 2-3 个执行周期（RED → GREEN → REFACTOR），每个周期都涉及文件读取、测试运行和可能的调试。TDD 功能获得专门的计划，以确保整个周期内有完整的上下文可用。 + + + +## 何时 TDD 提高质量 + +**TDD 候选（创建 TDD 计划）：** +- 有明确输入/输出的业务逻辑 +- 有请求/响应契约的 API 端点 +- 数据转换、解析、格式化 +- 验证规则和约束 +- 有可测试行为的算法 +- 状态机和工作流 +- 有清晰规格的工具函数 + +**跳过 TDD（使用带 `type="auto"` 任务的标准计划）：** +- UI 布局、样式、视觉组件 +- 配置更改 +- 连接现有组件的胶水代码 +- 一次性脚本和迁移 +- 无业务逻辑的简单 CRUD +- 探索性原型 + +**启发式：** 能在编写 `fn` 之前写 `expect(fn(input)).toBe(output)` 吗？ +→ 能：创建 TDD 计划 +→ 不能：使用标准计划，事后添加测试（如需要） + + + +## TDD 计划结构 + +每个 TDD 计划通过完整的 RED-GREEN-REFACTOR 循环实现**一个功能**。 + +```markdown +--- +phase: XX-name +plan: NN +type: tdd +--- + + +[什么功能以及为什么] +Purpose: [该功能 TDD 的设计收益] +Output: [可工作的、已测试的功能] + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@relevant/source/files.ts + + + + [功能名称] + [源文件, 测试文件] + + [可测试术语描述的预期行为] + Cases: 输入 → 预期输出 + + [测试通过后如何实现] + + + +[证明功能有效的测试命令] + + + +- 失败测试已编写并提交 +- 实现通过测试 +- 重构完成（如需要） +- 所有 2-3 个提交都存在 + + + +完成后，创建包含以下内容的 SUMMARY.md： +- RED: 编写了什么测试，为什么失败 +- GREEN: 什么实现让它通过 +- REFACTOR: 做了什么清理（如有） +- Commits: 生成的提交列表 + +``` + +**每个 TDD 计划一个功能。** 如果功能足够简单可以批量处理，那就足够简单可以跳过 TDD —— 使用标准计划，事后添加测试。 + + + +## 红-绿-重构循环 + +**RED - 编写失败测试：** +1. 按项目约定创建测试文件 +2. 编写描述预期行为的测试（来自 `` 元素） +3. 运行测试 - 必须**失败** +4. 如果测试通过：功能已存在或测试有误。调查。 +5. 提交：`test({phase}-{plan}): add failing test for [feature]` + +**GREEN - 实现使其通过：** +1. 编写使测试通过的最小代码 +2. 不耍小聪明，不优化 - 只让它工作 +3. 运行测试 - 必须**通过** +4. 提交：`feat({phase}-{plan}): implement [feature]` + +**REFACTOR（如需要）：** +1. 如果存在明显的改进，清理实现 +2. 运行测试 - 必须**仍然通过** +3. 仅在做出更改时提交：`refactor({phase}-{plan}): clean up [feature]` + +**结果：** 每个 TDD 计划产生 2-3 个原子提交。 + + + +## 好测试 vs 坏测试 + +**测试行为，而非实现：** +- 好："返回格式化的日期字符串" +- 坏："用正确参数调用 formatDate 辅助函数" +- 测试应该能经受重构 + +**每个测试一个概念：** +- 好：分别为有效输入、空输入、畸形输入编写测试 +- 坏：用多个断言检查所有边缘情况的单个测试 + +**描述性名称：** +- 好："should reject empty email"、"returns null for invalid ID" +- 坏："test1"、"handles error"、"works correctly" + +**不包含实现细节：** +- 好：测试公共 API、可观察行为 +- 坏：Mock 内部实现、测试私有方法、断言内部状态 + + + +## 测试框架设置（如不存在） + +当执行 TDD 计划但没有配置测试框架时，作为 RED 阶段的一部分进行设置： + +**1. 检测项目类型：** +```bash +# JavaScript/TypeScript +if [ -f package.json ]; then echo "node"; fi + +# Python +if [ -f requirements.txt ] || [ -f pyproject.toml ]; then echo "python"; fi + +# Go +if [ -f go.mod ]; then echo "go"; fi + +# Rust +if [ -f Cargo.toml ]; then echo "rust"; fi +``` + +**2. 安装最小框架：** +| 项目 | 框架 | 安装 | +|---------|-----------|---------| +| Node.js | Jest | `npm install -D jest @types/jest ts-jest` | +| Node.js (Vite) | Vitest | `npm install -D vitest` | +| Python | pytest | `pip install pytest` | +| Go | testing | 内置 | +| Rust | cargo test | 内置 | + +**3. 按需创建配置：** +- Jest: 带 ts-jest preset 的 `jest.config.js` +- Vitest: 带测试全局变量的 `vitest.config.ts` +- pytest: `pytest.ini` 或 `pyproject.toml` 部分 + +**4. 验证设置：** +```bash +# 运行空测试套件 - 应该以 0 个测试通过 +npm test # Node +pytest # Python +go test ./... # Go +cargo test # Rust +``` + +**5. 创建第一个测试文件：** +遵循项目约定的测试位置： +- 源文件旁边的 `*.test.ts` / `*.spec.ts` +- `__tests__/` 目录 +- 根目录的 `tests/` 目录 + +框架设置是第一个 TDD 计划 RED 阶段的一次性成本。 + + + +## 错误处理 + +**测试在 RED 阶段没有失败：** +- 功能可能已存在 - 调查 +- 测试可能有误（没测试你以为的东西） +- 前进前修复 + +**测试在 GREEN 阶段没有通过：** +- 调试实现 +- 不要跳到重构 +- 持续迭代直到绿色 + +**测试在 REFACTOR 阶段失败：** +- 撤销重构 +- 提交过早 +- 用更小的步骤重构 + +**不相关的测试失败：** +- 停下来调查 +- 可能表明耦合问题 +- 前进前修复 + + + +## TDD 计划的提交模式 + +TDD 计划产生 2-3 个原子提交（每个阶段一个）： + +``` +test(08-02): add failing test for email validation + +- Tests valid email formats accepted +- Tests invalid formats rejected +- Tests empty input handling + +feat(08-02): implement email validation + +- Regex pattern matches RFC 5322 +- Returns boolean for validity +- Handles edge cases (empty, null) + +refactor(08-02): extract regex to constant (optional) + +- Moved pattern to EMAIL_REGEX constant +- No behavior changes +- Tests still pass +``` + +**与标准计划对比：** +- 标准计划：每个任务 1 个提交，每个计划 2-4 个提交 +- TDD 计划：单个功能 2-3 个提交 + +两者遵循相同格式：`{type}({phase}-{plan}): {description}` + +**好处：** +- 每个提交独立可回滚 +- Git bisect 在提交级别工作 +- 显示 TDD 纪律的清晰历史 +- 与整体提交策略一致 + + + +## 上下文预算 + +TDD 计划目标 **~40% 上下文使用率**（低于标准计划的 ~50%）。 + +为什么更低： +- RED 阶段：编写测试、运行测试、可能调试为什么没有失败 +- GREEN 阶段：实现、运行测试、可能对失败进行迭代 +- REFACTOR 阶段：修改代码、运行测试、验证无回归 + +每个阶段涉及读取文件、运行命令、分析输出。来回往复本质上比线性任务执行更重。 + +单一功能聚焦确保整个周期保持完整质量。 + \ No newline at end of file diff --git a/gsd-opencode/docs/zh-CN/references/ui-brand.md b/gsd-opencode/docs/zh-CN/references/ui-brand.md new file mode 100644 index 0000000..9e4e0d7 --- /dev/null +++ b/gsd-opencode/docs/zh-CN/references/ui-brand.md @@ -0,0 +1,158 @@ +# UI 品牌规范 + +面向用户的 GSD 输出的视觉模式。编排器通过 @ 引用此文件。 + +## 阶段横幅 + +用于主要工作流过渡。 + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► {阶段名称} +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +**阶段名称（大写）：** +- `QUESTIONING`（提问） +- `RESEARCHING`（研究） +- `DEFINING REQUIREMENTS`（定义需求） +- `CREATING ROADMAP`（创建路线图） +- `PLANNING PHASE {N}`（规划阶段 {N}） +- `EXECUTING WAVE {N}`（执行波次 {N}） +- `VERIFYING`（验证） +- `PHASE {N} COMPLETE ✓`（阶段 {N} 完成） +- `MILESTONE COMPLETE 🎉`（里程碑完成） + +--- + +## 检查点框 + +需要用户操作。62 字符宽度。 + +``` +╔══════════════════════════════════════════════════════════════╗ +║ CHECKPOINT: {类型} ║ +╚══════════════════════════════════════════════════════════════╝ + +{内容} + +────────────────────────────────────────────────────────────── +→ {操作提示} +────────────────────────────────────────────────────────────── +``` + +**类型：** +- `CHECKPOINT: 需要验证` → `→ 输入 "approved" 或描述问题` +- `CHECKPOINT: 需要决策` → `→ 选择: option-a / option-b` +- `CHECKPOINT: 需要操作` → `→ 完成后输入 "done"` + +--- + +## 状态符号 + +``` +✓ 完成 / 通过 / 已验证 +✗ 失败 / 缺失 / 阻塞 +◆ 进行中 +○ 待处理 +⚡ 自动批准 +⚠ 警告 +🎉 里程碑完成（仅在横幅中） +``` + +--- + +## 进度显示 + +**阶段/里程碑级别：** +``` +进度: ████████░░ 80% +``` + +**任务级别：** +``` +任务: 2/4 完成 +``` + +**计划级别：** +``` +计划: 3/5 完成 +``` + +--- + +## 生成指示器 + +``` +◆ 正在生成研究员... + +◆ 并行生成 4 个研究员... + → 技术栈研究 + → 功能研究 + → 架构研究 + → 陷阱研究 + +✓ 研究员完成: STACK.md 已写入 +``` + +--- + +## 下一步区块 + +始终在主要完成后。 + +``` +─────────────────────────────────────────────────────────────── + +## ▶ 下一步 + +**{标识符}: {名称}** — {单行描述} + +`{可复制粘贴的命令}` + +*`/new` 优先 → 全新上下文窗口* + +─────────────────────────────────────────────────────────────── + +**也可选：** +- `/gsd-alternative-1` — 描述 +- `/gsd-alternative-2` — 描述 + +─────────────────────────────────────────────────────────────── +``` + +--- + +## 错误框 + +``` +╔══════════════════════════════════════════════════════════════╗ +║ ERROR ║ +╚══════════════════════════════════════════════════════════════╝ + +{错误描述} + +**修复方法:** {解决步骤} +``` + +--- + +## 表格 + +``` +| 阶段 | 状态 | 计划 | 进度 | +|------|------|------|------| +| 1 | ✓ | 3/3 | 100% | +| 2 | ◆ | 1/4 | 25% | +| 3 | ○ | 0/2 | 0% | +``` + +--- + +## 反模式 + +- 变化的框/横幅宽度 +- 混合横幅样式（`===`、`---`、`***`） +- 横幅中缺少 `GSD ►` 前缀 +- 随机 emoji（`🚀`、`✨`、`💫`） +- 完成后缺少下一步区块 \ No newline at end of file diff --git a/gsd-opencode/docs/zh-CN/references/verification-patterns.md b/gsd-opencode/docs/zh-CN/references/verification-patterns.md new file mode 100644 index 0000000..2ddf44d --- /dev/null +++ b/gsd-opencode/docs/zh-CN/references/verification-patterns.md @@ -0,0 +1,612 @@ +# 验证模式 + +如何验证不同类型的工件是真实实现，而非存根或占位符。 + + +**存在 ≠ 实现** + +文件存在并不意味着功能有效。验证必须检查： +1. **存在** - 文件在预期路径 +2. **实质性** - 内容是真实实现，非占位符 +3. **已连接** - 已连接到系统的其他部分 +4. **功能性** - 调用时实际工作 + +级别 1-3 可以编程检查。级别 4 通常需要人工验证。 + + + + +## 通用存根模式 + +这些模式表明占位符代码，无论文件类型： + +**基于注释的存根：** +```bash +# 存根注释的 grep 模式 +grep -E "(TODO|FIXME|XXX|HACK|PLACEHOLDER)" "$file" +grep -E "implement|add later|coming soon|will be" "$file" -i +grep -E "// \.\.\.|/\* \.\.\. \*/|# \.\.\." "$file" +``` + +**输出中的占位符文本：** +```bash +# UI 占位符模式 +grep -E "placeholder|lorem ipsum|coming soon|under construction" "$file" -i +grep -E "sample|example|test data|dummy" "$file" -i +grep -E "\[.*\]|<.*>|\{.*\}" "$file" # 模板括号未移除 +``` + +**空或琐碎实现：** +```bash +# 什么都不做的函数 +grep -E "return null|return undefined|return \{\}|return \[\]" "$file" +grep -E "pass$|\.\.\.|\bnothing\b" "$file" +grep -E "console\.(log|warn|error).*only" "$file" # 仅日志函数 +``` + +**预期动态但硬编码的值：** +```bash +# 硬编码 ID、计数或内容 +grep -E "id.*=.*['\"].*['\"]" "$file" # 硬编码字符串 ID +grep -E "count.*=.*\d+|length.*=.*\d+" "$file" # 硬编码计数 +grep -E "\\\$\d+\.\d{2}|\d+ items" "$file" # 硬编码显示值 +``` + + + + + +## React/Next.js 组件 + +**存在检查：** +```bash +# 文件存在且导出组件 +[ -f "$component_path" ] && grep -E "export (default |)function|export const.*=.*\(" "$component_path" +``` + +**实质性检查：** +```bash +# 返回实际 JSX，非占位符 +grep -E "return.*<" "$component_path" | grep -v "return.*null" | grep -v "placeholder" -i + +# 有有意义的内容（不仅仅是包装 div） +grep -E "<[A-Z][a-zA-Z]+|className=|onClick=|onChange=" "$component_path" + +# 使用 props 或 state（非静态） +grep -E "props\.|useState|useEffect|useContext|\{.*\}" "$component_path" +``` + +**React 特有的存根模式：** +```javascript +// 危险信号 - 这些是存根： +return
Component
+return
Placeholder
+return
{/* TODO */}
+return

Coming soon

+return null +return <> + +// 也是存根 - 空处理器： +onClick={() => {}} +onChange={() => console.log('clicked')} +onSubmit={(e) => e.preventDefault()} // 仅阻止默认，什么都不做 +``` + +**连接检查：** +```bash +# 组件导入它需要的东西 +grep -E "^import.*from" "$component_path" + +# Props 实际被使用（不仅仅是接收） +# 查找解构或 props.X 用法 +grep -E "\{ .* \}.*props|\bprops\.[a-zA-Z]+" "$component_path" + +# API 调用存在（对于数据获取组件） +grep -E "fetch\(|axios\.|useSWR|useQuery|getServerSideProps|getStaticProps" "$component_path" +``` + +**功能验证（需要人工）：** +- 组件是否渲染可见内容？ +- 交互元素是否响应点击？ +- 数据是否加载并显示？ +- 错误状态是否适当显示？ + + + + + +## API 路由（Next.js App Router / Express 等） + +**存在检查：** +```bash +# 路由文件存在 +[ -f "$route_path" ] + +# 导出 HTTP 方法处理器（Next.js App Router） +grep -E "export (async )?(function|const) (GET|POST|PUT|PATCH|DELETE)" "$route_path" + +# 或 Express 风格处理器 +grep -E "\.(get|post|put|patch|delete)\(" "$route_path" +``` + +**实质性检查：** +```bash +# 有实际逻辑，不仅仅是 return 语句 +wc -l "$route_path" # 超过 10-15 行表明真实实现 + +# 与数据源交互 +grep -E "prisma\.|db\.|mongoose\.|sql|query|find|create|update|delete" "$route_path" -i + +# 有错误处理 +grep -E "try|catch|throw|error|Error" "$route_path" + +# 返回有意义的响应 +grep -E "Response\.json|res\.json|res\.send|return.*\{" "$route_path" | grep -v "message.*not implemented" -i +``` + +**API 路由特有的存根模式：** +```typescript +// 危险信号 - 这些是存根： +export async function POST() { + return Response.json({ message: "Not implemented" }) +} + +export async function GET() { + return Response.json([]) // 空 array 无数据库查询 +} + +export async function PUT() { + return new Response() // 空响应 +} + +// 仅控制台日志： +export async function POST(req) { + console.log(await req.json()) + return Response.json({ ok: true }) +} +``` + +**连接检查：** +```bash +# 导入数据库/服务客户端 +grep -E "^import.*prisma|^import.*db|^import.*client" "$route_path" + +# 实际使用请求体（对于 POST/PUT） +grep -E "req\.json\(\)|req\.body|request\.json\(\)" "$route_path" + +# 验证输入（不仅仅信任请求） +grep -E "schema\.parse|validate|zod|yup|joi" "$route_path" +``` + +**功能验证（人工或自动化）：** +- GET 是否从数据库返回真实数据？ +- POST 是否实际创建记录？ +- 错误响应是否有正确的状态码？ +- 认证检查是否实际执行？ + + + + + +## 数据库模式（Prisma / Drizzle / SQL） + +**存在检查：** +```bash +# 模式文件存在 +[ -f "prisma/schema.prisma" ] || [ -f "drizzle/schema.ts" ] || [ -f "src/db/schema.sql" ] + +# 模型/表已定义 +grep -E "^model $model_name|CREATE TABLE $table_name|export const $table_name" "$schema_path" +``` + +**实质性检查：** +```bash +# 有预期字段（不仅仅是 id） +grep -A 20 "model $model_name" "$schema_path" | grep -E "^\s+\w+\s+\w+" + +# 有预期关系 +grep -E "@relation|REFERENCES|FOREIGN KEY" "$schema_path" + +# 有适当的字段类型（不全是 String） +grep -A 20 "model $model_name" "$schema_path" | grep -E "Int|DateTime|Boolean|Float|Decimal|Json" +``` + +**模式特有的存根模式：** +```prisma +// 危险信号 - 这些是存根： +model User { + id String @id + // TODO: add fields +} + +model Message { + id String @id + content String // 只有一个真实字段 +} + +// 缺少关键字段： +model Order { + id String @id + // 缺少: userId, items, total, status, createdAt +} +``` + +**连接检查：** +```bash +# 迁移存在且已应用 +ls prisma/migrations/ 2>/dev/null | wc -l # 应该 > 0 +npx prisma migrate status 2>/dev/null | grep -v "pending" + +# 客户端已生成 +[ -d "node_modules/.prisma/client" ] +``` + +**功能验证：** +```bash +# 可以查询表（自动化） +npx prisma db execute --stdin <<< "SELECT COUNT(*) FROM $table_name" +``` + + + + + +## 自定义 Hooks 和工具 + +**存在检查：** +```bash +# 文件存在且导出函数 +[ -f "$hook_path" ] && grep -E "export (default )?(function|const)" "$hook_path" +``` + +**实质性检查：** +```bash +# Hook 使用 React hooks（对于自定义 hooks） +grep -E "useState|useEffect|useCallback|useMemo|useRef|useContext" "$hook_path" + +# 有有意义的返回值 +grep -E "return \{|return \[" "$hook_path" + +# 超过琐碎长度 +[ $(wc -l < "$hook_path") -gt 10 ] +``` + +**Hooks 特有的存根模式：** +```typescript +// 危险信号 - 这些是存根： +export function useAuth() { + return { user: null, login: () => {}, logout: () => {} } +} + +export function useCart() { + const [items, setItems] = useState([]) + return { items, addItem: () => console.log('add'), removeItem: () => {} } +} + +// 硬编码返回： +export function useUser() { + return { name: "Test User", email: "test@example.com" } +} +``` + +**连接检查：** +```bash +# Hook 实际在某处被导入 +grep -r "import.*$hook_name" src/ --include="*.tsx" --include="*.ts" | grep -v "$hook_path" + +# Hook 实际被调用 +grep -r "$hook_name()" src/ --include="*.tsx" --include="*.ts" | grep -v "$hook_path" +``` + + + + + +## 环境变量和配置 + +**存在检查：** +```bash +# .env 文件存在 +[ -f ".env" ] || [ -f ".env.local" ] + +# 必需变量已定义 +grep -E "^$VAR_NAME=" .env .env.local 2>/dev/null +``` + +**实质性检查：** +```bash +# 变量有实际值（非占位符） +grep -E "^$VAR_NAME=.+" .env .env.local 2>/dev/null | grep -v "your-.*-here|xxx|placeholder|TODO" -i + +# 值对类型看起来有效： +# - URL 应以 http 开头 +# - 密钥应足够长 +# - 布尔值应为 true/false +``` + +**环境变量特有的存根模式：** +```bash +# 危险信号 - 这些是存根： +DATABASE_URL=your-database-url-here +STRIPE_SECRET_KEY=sk_test_xxx +API_KEY=placeholder +NEXT_PUBLIC_API_URL=http://localhost:3000 # 生产环境仍指向 localhost +``` + +**连接检查：** +```bash +# 变量实际在代码中使用 +grep -r "process\.env\.$VAR_NAME|env\.$VAR_NAME" src/ --include="*.ts" --include="*.tsx" + +# 变量在验证模式中（如果使用 zod 等验证 env） +grep -E "$VAR_NAME" src/env.ts src/env.mjs 2>/dev/null +``` + + + + + +## 连接验证模式 + +连接验证检查组件是否实际通信。这是大多数存根隐藏的地方。 + +### 模式：组件 → API + +**检查：** 组件是否实际调用 API？ + +```bash +# 查找 fetch/axios 调用 +grep -E "fetch\(['\"].*$api_path|axios\.(get|post).*$api_path" "$component_path" + +# 验证未被注释掉 +grep -E "fetch\(|axios\." "$component_path" | grep -v "^.*//.*fetch" + +# 检查响应被使用 +grep -E "await.*fetch|\.then\(|setData|setState" "$component_path" +``` + +**危险信号：** +```typescript +// Fetch 存在但响应被忽略： +fetch('/api/messages') // 无 await，无 .then，无赋值 + +// Fetch 在注释中： +// fetch('/api/messages').then(r => r.json()).then(setMessages) + +// Fetch 到错误的端点： +fetch('/api/message') // 拼写错误 - 应该是 /api/messages +``` + +### 模式：API → 数据库 + +**检查：** API 路由是否实际查询数据库？ + +```bash +# 查找数据库调用 +grep -E "prisma\.$model|db\.query|Model\.find" "$route_path" + +# 验证被 await +grep -E "await.*prisma|await.*db\." "$route_path" + +# 检查结果被返回 +grep -E "return.*json.*data|res\.json.*result" "$route_path" +``` + +**危险信号：** +```typescript +// 查询存在但结果未返回： +await prisma.message.findMany() +return Response.json({ ok: true }) // 返回静态值，非查询结果 + +// 查询未被 await： +const messages = prisma.message.findMany() // 缺少 await +return Response.json(messages) // 返回 Promise，非数据 +``` + +### 模式：表单 → 处理器 + +**检查：** 表单提交是否实际做些什么？ + +```bash +# 查找 onSubmit 处理器 +grep -E "onSubmit=\{|handleSubmit" "$component_path" + +# 检查处理器有内容 +grep -A 10 "onSubmit.*=" "$component_path" | grep -E "fetch|axios|mutate|dispatch" + +# 验证不仅仅是 preventDefault +grep -A 5 "onSubmit" "$component_path" | grep -v "only.*preventDefault" -i +``` + +**危险信号：** +```typescript +// 处理器仅阻止默认： +onSubmit={(e) => e.preventDefault()} + +// 处理器仅日志： +const handleSubmit = (data) => { + console.log(data) +} + +// 处理器为空： +onSubmit={() => {}} +``` + +### 模式：状态 → 渲染 + +**检查：** 组件是否渲染状态，而非硬编码内容？ + +```bash +# 查找 JSX 中的状态使用 +grep -E "\{.*messages.*\}|\{.*data.*\}|\{.*items.*\}" "$component_path" + +# 检查状态的 map/render +grep -E "\.map\(|\.filter\(|\.reduce\(" "$component_path" + +# 验证动态内容 +grep -E "\{[a-zA-Z_]+\." "$component_path" # 变量插值 +``` + +**危险信号：** +```tsx +// 硬编码而非状态： +return
+

Message 1

+

Message 2

+
+ +// 状态存在但未渲染： +const [messages, setMessages] = useState([]) +return
No messages
// 总是显示 "no messages" + +// 渲染错误的状态： +const [messages, setMessages] = useState([]) +return
{otherData.map(...)}
// 使用不同数据 +``` + + + + + +## 快速验证清单 + +对于每种工件类型，运行此清单： + +### 组件清单 +- [ ] 文件存在于预期路径 +- [ ] 导出函数/const 组件 +- [ ] 返回 JSX（非 null/空） +- [ ] 渲染中无占位符文本 +- [ ] 使用 props 或 state（非静态） +- [ ] 事件处理器有真实实现 +- [ ] 导入正确解析 +- [ ] 在应用某处被使用 + +### API 路由清单 +- [ ] 文件存在于预期路径 +- [ ] 导出 HTTP 方法处理器 +- [ ] 处理器超过 5 行 +- [ ] 查询数据库或服务 +- [ ] 返回有意义的响应（非空/占位符） +- [ ] 有错误处理 +- [ ] 验证输入 +- [ ] 从前端调用 + +### 模式清单 +- [ ] 模型/表已定义 +- [ ] 有所有预期字段 +- [ ] 字段有适当类型 +- [ ] 如需要关系已定义 +- [ ] 迁移存在且已应用 +- [ ] 客户端已生成 + +### Hook/工具清单 +- [ ] 文件存在于预期路径 +- [ ] 导出函数 +- [ ] 有有意义的实现（非空返回） +- [ ] 在应用某处被使用 +- [ ] 返回值被消费 + +### 连接清单 +- [ ] 组件 → API: fetch/axios 调用存在且使用响应 +- [ ] API → 数据库: 查询存在且结果返回 +- [ ] 表单 → 处理器: onSubmit 调用 API/mutation +- [ ] 状态 → 渲染: 状态变量出现在 JSX 中 + + + + + +## 自动化验证方法 + +对于验证子代理，使用此模式： + +```bash +# 1. 检查存在 +check_exists() { + [ -f "$1" ] && echo "EXISTS: $1" || echo "MISSING: $1" +} + +# 2. 检查存根模式 +check_stubs() { + local file="$1" + local stubs=$(grep -c -E "TODO|FIXME|placeholder|not implemented" "$file" 2>/dev/null || echo 0) + [ "$stubs" -gt 0 ] && echo "STUB_PATTERNS: $stubs in $file" +} + +# 3. 检查连接（组件调用 API） +check_wiring() { + local component="$1" + local api_path="$2" + grep -q "$api_path" "$component" && echo "WIRED: $component → $api_path" || echo "NOT_WIRED: $component → $api_path" +} + +# 4. 检查实质性（超过 N 行，有预期模式） +check_substantive() { + local file="$1" + local min_lines="$2" + local pattern="$3" + local lines=$(wc -l < "$file" 2>/dev/null || echo 0) + local has_pattern=$(grep -c -E "$pattern" "$file" 2>/dev/null || echo 0) + [ "$lines" -ge "$min_lines" ] && [ "$has_pattern" -gt 0 ] && echo "SUBSTANTIVE: $file" || echo "THIN: $file ($lines lines, $has_pattern matches)" +} +``` + +对每个必须有工件运行这些检查。汇总结果到 VERIFICATION.md。 + + + + + +## 何时需要人工验证 + +有些事情无法编程验证。标记这些需要人工测试： + +**始终人工：** +- 视觉外观（看起来对吗？） +- 用户流程完成（能实际做那件事吗？） +- 实时行为（WebSocket、SSE） +- 外部服务集成（Stripe、邮件发送） +- 错误消息清晰度（消息有帮助吗？） +- 性能感觉（感觉快吗？） + +**如不确定则人工：** +- grep 无法追踪的复杂连接 +- 依赖状态的动态行为 +- 边缘情况和错误状态 +- 移动端响应式 +- 无障碍性 + +**人工验证请求格式：** +```markdown +## 需要人工验证 + +### 1. 聊天消息发送 +**测试：** 输入消息并点击发送 +**预期：** 消息出现在列表中，输入框清空 +**检查：** 刷新后消息是否持久？ + +### 2. 错误处理 +**测试：** 断开网络，尝试发送 +**预期：** 错误消息出现，消息未丢失 +**检查：** 重连后能重试吗？ +``` + + + + + +## 检查点前自动化 + +关于自动化优先的检查点模式、服务器生命周期管理、CLI 安装处理和错误恢复协议，请参阅： + +**@$HOME/.config/opencode/get-shit-done/references/checkpoints.md** → `` 部分 + +关键原则： +- OpenCode 在呈现检查点**之前**设置验证环境 +- 用户从不运行 CLI 命令（仅访问 URL） +- 服务器生命周期：检查点前启动、处理端口冲突、持续运行 +- CLI 安装：安全处自动安装，否则检查点让用户选择 +- 错误处理：检查点前修复损坏环境，绝不呈现有失败设置的检查点 + + \ No newline at end of file diff --git a/gsd-opencode/get-shit-done/bin/gsd-tools.cjs b/gsd-opencode/get-shit-done/bin/gsd-tools.cjs index 48cb9cf..364e37d 100755 --- a/gsd-opencode/get-shit-done/bin/gsd-tools.cjs +++ b/gsd-opencode/get-shit-done/bin/gsd-tools.cjs @@ -6,7 +6,7 @@ * Replaces repetitive inline bash patterns across ~50 GSD command/workflow/agent files. * Centralizes: config parsing, model resolution, phase lookup, git commits, summary verification. * - * Usage: node gsd-tools.cjs [args] [--raw] + * Usage: node gsd-tools.cjs [args] [--raw] [--pick ] * * Atomic Commands: * state load Load project config + state @@ -14,9 +14,13 @@ * state update Update a STATE.md field * state get [section] Get STATE.md content or section * state patch --field val ... Batch update STATE.md fields + * state begin-phase --phase N --name S --plans C Update STATE.md for new phase start + * state signal-waiting --type T --question Q --options "A|B" --phase P write WAITING.json signal + * state signal-resume Remove WAITING.json signal * resolve-model Get model for agent based on profile * find-phase Find phase directory by number - * commit [--files f1 f2] Commit planning docs + * commit [--files f1 f2] [--no-verify] Commit planning docs + * commit-to-subrepo --files f1 f2 Route commits to sub-repos * verify-summary Verify a SUMMARY.md file * generate-slug Convert text to URL-safe slug * current-timestamp [format] Get timestamp (full|date|filename) @@ -32,7 +36,7 @@ * * Phase Operations: * phase next-decimal Calculate next decimal phase number - * phase add Append new phase to roadmap + create dir + * phase add [--id ID] Append new phase to roadmap + create dir * phase insert Insert decimal phase after existing * phase remove [--force] Remove phase, renumber all subsequent * phase complete Mark phase done, update state + roadmap @@ -54,6 +58,7 @@ * Validation: * validate consistency Check phase numbering, disk/roadmap sync * validate health [--repair] Check .planning/ integrity, optionally repair + * validate agents Check GSD agent installation status * * Progress: * progress [json|table|bar] Render progress in various formats @@ -61,6 +66,10 @@ * Todos: * todo complete Move todo from pending to completed * + * UAT Audit: + * audit-uat Scan all phases for unresolved UAT/verification items + * uat render-checkpoint --file Render the current UAT checkpoint block + * * Scaffolding: * scaffold context --phase Create CONTEXT.md template * scaffold uat --phase Create UAT.md template @@ -128,7 +137,8 @@ const fs = require('fs'); const path = require('path'); -const { error } = require('./lib/core.cjs'); +const core = require('./lib/core.cjs'); +const { error, findProjectRoot, getActiveWorkstream } = core; const state = require('./lib/state.cjs'); const phase = require('./lib/phase.cjs'); const roadmap = require('./lib/roadmap.cjs'); @@ -139,6 +149,49 @@ const milestone = require('./lib/milestone.cjs'); const commands = require('./lib/commands.cjs'); const init = require('./lib/init.cjs'); const frontmatter = require('./lib/frontmatter.cjs'); +const profilePipeline = require('./lib/profile-pipeline.cjs'); +const profileOutput = require('./lib/profile-output.cjs'); +const workstream = require('./lib/workstream.cjs'); + +// ─── Arg parsing helpers ────────────────────────────────────────────────────── + +/** + * Extract named --flag pairs from an args array. + * Returns an object mapping flag names to their values (null if absent). + * Flags listed in `booleanFlags` are treated as boolean (no value consumed). + * + * parseNamedArgs(args, 'phase', 'plan') → { phase: '3', plan: '1' } + * parseNamedArgs(args, [], ['amend', 'force']) → { amend: true, force: false } + */ +function parseNamedArgs(args, valueFlags = [], booleanFlags = []) { + const result = {}; + for (const flag of valueFlags) { + const idx = args.indexOf(`--${flag}`); + result[flag] = idx !== -1 && args[idx + 1] !== undefined && !args[idx + 1].startsWith('--') + ? args[idx + 1] + : null; + } + for (const flag of booleanFlags) { + result[flag] = args.includes(`--${flag}`); + } + return result; +} + +/** + * Collect all tokens after --flag until the next --flag or end of args. + * Handles multi-word values like --name Foo Bar Version 1. + * Returns null if the flag is absent. + */ +function parseMultiwordArg(args, flag) { + const idx = args.indexOf(`--${flag}`); + if (idx === -1) return null; + const tokens = []; + for (let i = idx + 1; i < args.length; i++) { + if (args[i].startsWith('--')) break; + tokens.push(args[i]); + } + return tokens.length > 0 ? tokens.join(' ') : null; +} // ─── CLI Router ─────────────────────────────────────────────────────────────── @@ -165,16 +218,137 @@ async function main() { error(`Invalid --cwd: ${cwd}`); } + // Resolve worktree root: in a linked worktree, .planning/ lives in the main worktree. + // However, in monorepo worktrees where the subdirectory itself owns .planning/, + // skip worktree resolution — the CWD is already the correct project root. + const { resolveWorktreeRoot } = require('./lib/core.cjs'); + if (!fs.existsSync(path.join(cwd, '.planning'))) { + const worktreeRoot = resolveWorktreeRoot(cwd); + if (worktreeRoot !== cwd) { + cwd = worktreeRoot; + } + } + + // Optional workstream override for parallel milestone work. + // Priority: --ws flag > GSD_WORKSTREAM env var > active-workstream file > null (flat mode) + const wsEqArg = args.find(arg => arg.startsWith('--ws=')); + const wsIdx = args.indexOf('--ws'); + let ws = null; + if (wsEqArg) { + ws = wsEqArg.slice('--ws='.length).trim(); + if (!ws) error('Missing value for --ws'); + args.splice(args.indexOf(wsEqArg), 1); + } else if (wsIdx !== -1) { + ws = args[wsIdx + 1]; + if (!ws || ws.startsWith('--')) error('Missing value for --ws'); + args.splice(wsIdx, 2); + } else if (process.env.GSD_WORKSTREAM) { + ws = process.env.GSD_WORKSTREAM.trim(); + } else { + ws = getActiveWorkstream(cwd); + } + // Validate workstream name to prevent path traversal attacks. + if (ws && !/^[a-zA-Z0-9_-]+$/.test(ws)) { + error('Invalid workstream name: must be alphanumeric, hyphens, and underscores only'); + } + // Set env var so all modules (planningDir, planningPaths) auto-resolve workstream paths + if (ws) { + process.env.GSD_WORKSTREAM = ws; + } + const rawIndex = args.indexOf('--raw'); const raw = rawIndex !== -1; if (rawIndex !== -1) args.splice(rawIndex, 1); + // --pick : extract a single field from JSON output (replaces jq dependency). + // Supports dot-notation (e.g., --pick workflow.research) and bracket notation + // for arrays (e.g., --pick directories[-1]). + const pickIdx = args.indexOf('--pick'); + let pickField = null; + if (pickIdx !== -1) { + pickField = args[pickIdx + 1]; + if (!pickField || pickField.startsWith('--')) error('Missing value for --pick'); + args.splice(pickIdx, 2); + } + const command = args[0]; if (!command) { - error('Usage: gsd-tools [args] [--raw] [--cwd ]\nCommands: state, resolve-model, find-phase, commit, verify-summary, verify, frontmatter, template, generate-slug, current-timestamp, list-todos, verify-path-exists, config-ensure-section, init'); + error('Usage: gsd-tools [args] [--raw] [--pick ] [--cwd ] [--ws ]\nCommands: state, resolve-model, find-phase, commit, verify-summary, verify, frontmatter, template, generate-slug, current-timestamp, list-todos, verify-path-exists, config-ensure-section, config-new-project, init, workstream'); + } + + // Multi-repo guard: resolve project root for commands that read/write .planning/. + // Skip for pure-utility commands that don't touch .planning/ to avoid unnecessary + // filesystem traversal on every invocation. + const SKIP_ROOT_RESOLUTION = new Set([ + 'generate-slug', 'current-timestamp', 'verify-path-exists', + 'verify-summary', 'template', 'frontmatter', + ]); + if (!SKIP_ROOT_RESOLUTION.has(command)) { + cwd = findProjectRoot(cwd); + } + + // When --pick is active, intercept stdout to extract the requested field. + if (pickField) { + const origWriteSync = fs.writeSync; + const chunks = []; + fs.writeSync = function (fd, data, ...rest) { + if (fd === 1) { chunks.push(String(data)); return; } + return origWriteSync.call(fs, fd, data, ...rest); + }; + const cleanup = () => { + fs.writeSync = origWriteSync; + const captured = chunks.join(''); + let jsonStr = captured; + if (jsonStr.startsWith('@file:')) { + jsonStr = fs.readFileSync(jsonStr.slice(6), 'utf-8'); + } + try { + const obj = JSON.parse(jsonStr); + const value = extractField(obj, pickField); + const result = value === null || value === undefined ? '' : String(value); + origWriteSync.call(fs, 1, result); + } catch { + origWriteSync.call(fs, 1, captured); + } + }; + try { + await runCommand(command, args, cwd, raw); + cleanup(); + } catch (e) { + fs.writeSync = origWriteSync; + throw e; + } + return; } + await runCommand(command, args, cwd, raw); +} + +/** + * Extract a field from an object using dot-notation and bracket syntax. + * Supports: 'field', 'parent.child', 'arr[-1]', 'arr[0]' + */ +function extractField(obj, fieldPath) { + const parts = fieldPath.split('.'); + let current = obj; + for (const part of parts) { + if (current === null || current === undefined) return undefined; + const bracketMatch = part.match(/^(.+?)\[(-?\d+)]$/); + if (bracketMatch) { + const key = bracketMatch[1]; + const index = parseInt(bracketMatch[2], 10); + current = current[key]; + if (!Array.isArray(current)) return undefined; + current = index < 0 ? current[current.length + index] : current[index]; + } else { + current = current[part]; + } + } + return current; +} + +async function runCommand(command, args, cwd, raw) { switch (command) { case 'state': { const subcommand = args[1]; @@ -197,50 +371,29 @@ async function main() { } else if (subcommand === 'advance-plan') { state.cmdStateAdvancePlan(cwd, raw); } else if (subcommand === 'record-metric') { - const phaseIdx = args.indexOf('--phase'); - const planIdx = args.indexOf('--plan'); - const durationIdx = args.indexOf('--duration'); - const tasksIdx = args.indexOf('--tasks'); - const filesIdx = args.indexOf('--files'); - state.cmdStateRecordMetric(cwd, { - phase: phaseIdx !== -1 ? args[phaseIdx + 1] : null, - plan: planIdx !== -1 ? args[planIdx + 1] : null, - duration: durationIdx !== -1 ? args[durationIdx + 1] : null, - tasks: tasksIdx !== -1 ? args[tasksIdx + 1] : null, - files: filesIdx !== -1 ? args[filesIdx + 1] : null, - }, raw); + const { phase: p, plan, duration, tasks, files } = parseNamedArgs(args, ['phase', 'plan', 'duration', 'tasks', 'files']); + state.cmdStateRecordMetric(cwd, { phase: p, plan, duration, tasks, files }, raw); } else if (subcommand === 'update-progress') { state.cmdStateUpdateProgress(cwd, raw); } else if (subcommand === 'add-decision') { - const phaseIdx = args.indexOf('--phase'); - const summaryIdx = args.indexOf('--summary'); - const summaryFileIdx = args.indexOf('--summary-file'); - const rationaleIdx = args.indexOf('--rationale'); - const rationaleFileIdx = args.indexOf('--rationale-file'); - state.cmdStateAddDecision(cwd, { - phase: phaseIdx !== -1 ? args[phaseIdx + 1] : null, - summary: summaryIdx !== -1 ? args[summaryIdx + 1] : null, - summary_file: summaryFileIdx !== -1 ? args[summaryFileIdx + 1] : null, - rationale: rationaleIdx !== -1 ? args[rationaleIdx + 1] : '', - rationale_file: rationaleFileIdx !== -1 ? args[rationaleFileIdx + 1] : null, - }, raw); + const { phase: p, summary, 'summary-file': summary_file, rationale, 'rationale-file': rationale_file } = parseNamedArgs(args, ['phase', 'summary', 'summary-file', 'rationale', 'rationale-file']); + state.cmdStateAddDecision(cwd, { phase: p, summary, summary_file, rationale: rationale || '', rationale_file }, raw); } else if (subcommand === 'add-blocker') { - const textIdx = args.indexOf('--text'); - const textFileIdx = args.indexOf('--text-file'); - state.cmdStateAddBlocker(cwd, { - text: textIdx !== -1 ? args[textIdx + 1] : null, - text_file: textFileIdx !== -1 ? args[textFileIdx + 1] : null, - }, raw); + const { text, 'text-file': text_file } = parseNamedArgs(args, ['text', 'text-file']); + state.cmdStateAddBlocker(cwd, { text, text_file }, raw); } else if (subcommand === 'resolve-blocker') { - const textIdx = args.indexOf('--text'); - state.cmdStateResolveBlocker(cwd, textIdx !== -1 ? args[textIdx + 1] : null, raw); + state.cmdStateResolveBlocker(cwd, parseNamedArgs(args, ['text']).text, raw); } else if (subcommand === 'record-session') { - const stoppedIdx = args.indexOf('--stopped-at'); - const resumeIdx = args.indexOf('--resume-file'); - state.cmdStateRecordSession(cwd, { - stopped_at: stoppedIdx !== -1 ? args[stoppedIdx + 1] : null, - resume_file: resumeIdx !== -1 ? args[resumeIdx + 1] : 'None', - }, raw); + const { 'stopped-at': stopped_at, 'resume-file': resume_file } = parseNamedArgs(args, ['stopped-at', 'resume-file']); + state.cmdStateRecordSession(cwd, { stopped_at, resume_file: resume_file || 'None' }, raw); + } else if (subcommand === 'begin-phase') { + const { phase: p, name, plans } = parseNamedArgs(args, ['phase', 'name', 'plans']); + state.cmdStateBeginPhase(cwd, p, name, plans !== null ? parseInt(plans, 10) : null, raw); + } else if (subcommand === 'signal-waiting') { + const { type, question, options, phase: p } = parseNamedArgs(args, ['type', 'question', 'options', 'phase']); + state.cmdSignalWaiting(cwd, type, question, options, p, raw); + } else if (subcommand === 'signal-resume') { + state.cmdSignalResume(cwd, raw); } else { state.cmdStateLoad(cwd, raw); } @@ -259,6 +412,7 @@ async function main() { case 'commit': { const amend = args.includes('--amend'); + const noVerify = args.includes('--no-verify'); const filesIndex = args.indexOf('--files'); // Collect all positional args between command name and first flag, // then join them — handles both quoted ("multi word msg") and @@ -267,7 +421,15 @@ async function main() { const messageArgs = args.slice(1, endIndex).filter(a => !a.startsWith('--')); const message = messageArgs.join(' ') || undefined; const files = filesIndex !== -1 ? args.slice(filesIndex + 1).filter(a => !a.startsWith('--')) : []; - commands.cmdCommit(cwd, message, files, raw, amend); + commands.cmdCommit(cwd, message, files, raw, amend, noVerify); + break; + } + + case 'commit-to-subrepo': { + const message = args[1]; + const filesIndex = args.indexOf('--files'); + const files = filesIndex !== -1 ? args.slice(filesIndex + 1).filter(a => !a.startsWith('--')) : []; + commands.cmdCommitToSubrepo(cwd, message, files, raw); break; } @@ -285,19 +447,18 @@ async function main() { template.cmdTemplateSelect(cwd, args[2], raw); } else if (subcommand === 'fill') { const templateType = args[2]; - const phaseIdx = args.indexOf('--phase'); - const planIdx = args.indexOf('--plan'); - const nameIdx = args.indexOf('--name'); - const typeIdx = args.indexOf('--type'); - const waveIdx = args.indexOf('--wave'); - const fieldsIdx = args.indexOf('--fields'); + const { phase, plan, name, type, wave, fields: fieldsRaw } = parseNamedArgs(args, ['phase', 'plan', 'name', 'type', 'wave', 'fields']); + let fields = {}; + if (fieldsRaw) { + const { safeJsonParse } = require('./lib/security.cjs'); + const result = safeJsonParse(fieldsRaw, { label: '--fields' }); + if (!result.ok) error(result.error); + fields = result.value; + } template.cmdTemplateFill(cwd, templateType, { - phase: phaseIdx !== -1 ? args[phaseIdx + 1] : null, - plan: planIdx !== -1 ? args[planIdx + 1] : null, - name: nameIdx !== -1 ? args[nameIdx + 1] : null, - type: typeIdx !== -1 ? args[typeIdx + 1] : 'execute', - wave: waveIdx !== -1 ? args[waveIdx + 1] : '1', - fields: fieldsIdx !== -1 ? JSON.parse(args[fieldsIdx + 1]) : {}, + phase, plan, name, fields, + type: type || 'execute', + wave: wave || '1', }, raw); } else { error('Unknown template subcommand. Available: select, fill'); @@ -309,18 +470,14 @@ async function main() { const subcommand = args[1]; const file = args[2]; if (subcommand === 'get') { - const fieldIdx = args.indexOf('--field'); - frontmatter.cmdFrontmatterGet(cwd, file, fieldIdx !== -1 ? args[fieldIdx + 1] : null, raw); + frontmatter.cmdFrontmatterGet(cwd, file, parseNamedArgs(args, ['field']).field, raw); } else if (subcommand === 'set') { - const fieldIdx = args.indexOf('--field'); - const valueIdx = args.indexOf('--value'); - frontmatter.cmdFrontmatterSet(cwd, file, fieldIdx !== -1 ? args[fieldIdx + 1] : null, valueIdx !== -1 ? args[valueIdx + 1] : undefined, raw); + const { field, value } = parseNamedArgs(args, ['field', 'value']); + frontmatter.cmdFrontmatterSet(cwd, file, field, value !== null ? value : undefined, raw); } else if (subcommand === 'merge') { - const dataIdx = args.indexOf('--data'); - frontmatter.cmdFrontmatterMerge(cwd, file, dataIdx !== -1 ? args[dataIdx + 1] : null, raw); + frontmatter.cmdFrontmatterMerge(cwd, file, parseNamedArgs(args, ['data']).data, raw); } else if (subcommand === 'validate') { - const schemaIdx = args.indexOf('--schema'); - frontmatter.cmdFrontmatterValidate(cwd, file, schemaIdx !== -1 ? args[schemaIdx + 1] : null, raw); + frontmatter.cmdFrontmatterValidate(cwd, file, parseNamedArgs(args, ['schema']).schema, raw); } else { error('Unknown frontmatter subcommand. Available: get, set, merge, validate'); } @@ -377,11 +534,26 @@ async function main() { break; } + case "config-set-model-profile": { + config.cmdConfigSetModelProfile(cwd, args[1], raw); + break; + } + case 'config-get': { config.cmdConfigGet(cwd, args[1], raw); break; } + case 'config-new-project': { + config.cmdConfigNewProject(cwd, args[1], raw); + break; + } + + case 'agent-skills': { + init.cmdAgentSkills(cwd, args[1], raw); + break; + } + case 'history-digest': { commands.cmdHistoryDigest(cwd, raw); break; @@ -433,7 +605,18 @@ async function main() { if (subcommand === 'next-decimal') { phase.cmdPhaseNextDecimal(cwd, args[2], raw); } else if (subcommand === 'add') { - phase.cmdPhaseAdd(cwd, args.slice(2).join(' '), raw); + const idIdx = args.indexOf('--id'); + let customId = null; + const descArgs = []; + for (let i = 2; i < args.length; i++) { + if (args[i] === '--id' && i + 1 < args.length) { + customId = args[i + 1]; + i++; // skip value + } else { + descArgs.push(args[i]); + } + } + phase.cmdPhaseAdd(cwd, descArgs.join(' '), raw, customId); } else if (subcommand === 'insert') { phase.cmdPhaseInsert(cwd, args[2], args.slice(3).join(' '), raw); } else if (subcommand === 'remove') { @@ -450,18 +633,8 @@ async function main() { case 'milestone': { const subcommand = args[1]; if (subcommand === 'complete') { - const nameIndex = args.indexOf('--name'); + const milestoneName = parseMultiwordArg(args, 'name'); const archivePhases = args.includes('--archive-phases'); - // Collect --name value (everything after --name until next flag or end) - let milestoneName = null; - if (nameIndex !== -1) { - const nameArgs = []; - for (let i = nameIndex + 1; i < args.length; i++) { - if (args[i].startsWith('--')) break; - nameArgs.push(args[i]); - } - milestoneName = nameArgs.join(' ') || null; - } milestone.cmdMilestoneComplete(cwd, args[2], { name: milestoneName, archivePhases }, raw); } else { error('Unknown milestone subcommand. Available: complete'); @@ -476,8 +649,10 @@ async function main() { } else if (subcommand === 'health') { const repairFlag = args.includes('--repair'); verify.cmdValidateHealth(cwd, { repair: repairFlag }, raw); + } else if (subcommand === 'agents') { + verify.cmdValidateAgents(cwd, raw); } else { - error('Unknown validate subcommand. Available: consistency, health'); + error('Unknown validate subcommand. Available: consistency, health, agents'); } break; } @@ -488,23 +663,47 @@ async function main() { break; } + case 'audit-uat': { + const uat = require('./lib/uat.cjs'); + uat.cmdAuditUat(cwd, raw); + break; + } + + case 'uat': { + const subcommand = args[1]; + const uat = require('./lib/uat.cjs'); + if (subcommand === 'render-checkpoint') { + const options = parseNamedArgs(args, ['file']); + uat.cmdRenderCheckpoint(cwd, options, raw); + } else { + error('Unknown uat subcommand. Available: render-checkpoint'); + } + break; + } + + case 'stats': { + const subcommand = args[1] || 'json'; + commands.cmdStats(cwd, subcommand, raw); + break; + } + case 'todo': { const subcommand = args[1]; if (subcommand === 'complete') { commands.cmdTodoComplete(cwd, args[2], raw); + } else if (subcommand === 'match-phase') { + commands.cmdTodoMatchPhase(cwd, args[2], raw); } else { - error('Unknown todo subcommand. Available: complete'); + error('Unknown todo subcommand. Available: complete, match-phase'); } break; } case 'scaffold': { const scaffoldType = args[1]; - const phaseIndex = args.indexOf('--phase'); - const nameIndex = args.indexOf('--name'); const scaffoldOptions = { - phase: phaseIndex !== -1 ? args[phaseIndex + 1] : null, - name: nameIndex !== -1 ? args.slice(nameIndex + 1).join(' ') : null, + phase: parseNamedArgs(args, ['phase']).phase, + name: parseMultiwordArg(args, 'name'), }; commands.cmdScaffold(cwd, scaffoldType, scaffoldOptions, raw); break; @@ -549,8 +748,20 @@ async function main() { case 'progress': init.cmdInitProgress(cwd, raw); break; + case 'manager': + init.cmdInitManager(cwd, raw); + break; + case 'new-workspace': + init.cmdInitNewWorkspace(cwd, raw); + break; + case 'list-workspaces': + init.cmdInitListWorkspaces(cwd, raw); + break; + case 'remove-workspace': + init.cmdInitRemoveWorkspace(cwd, args[2], raw); + break; default: - error(`Unknown init workflow: ${workflow}\nAvailable: execute-phase, plan-phase, new-project, new-milestone, quick, resume, verify-work, phase-op, todos, milestone-op, map-codebase, progress`); + error(`Unknown init workflow: ${workflow}\nAvailable: execute-phase, plan-phase, new-project, new-milestone, quick, resume, verify-work, phase-op, todos, milestone-op, map-codebase, progress, manager, new-workspace, list-workspaces, remove-workspace`); } break; } @@ -584,6 +795,121 @@ async function main() { break; } + // ─── Profiling Pipeline ──────────────────────────────────────────────── + + case 'scan-sessions': { + const pathIdx = args.indexOf('--path'); + const sessionsPath = pathIdx !== -1 ? args[pathIdx + 1] : null; + const verboseFlag = args.includes('--verbose'); + const jsonFlag = args.includes('--json'); + await profilePipeline.cmdScanSessions(sessionsPath, { verbose: verboseFlag, json: jsonFlag }, raw); + break; + } + + case 'extract-messages': { + const sessionIdx = args.indexOf('--session'); + const sessionId = sessionIdx !== -1 ? args[sessionIdx + 1] : null; + const limitIdx = args.indexOf('--limit'); + const limit = limitIdx !== -1 ? parseInt(args[limitIdx + 1], 10) : null; + const pathIdx = args.indexOf('--path'); + const sessionsPath = pathIdx !== -1 ? args[pathIdx + 1] : null; + const projectArg = args[1]; + if (!projectArg || projectArg.startsWith('--')) { + error('Usage: gsd-tools extract-messages [--session ] [--limit N] [--path ]\nRun scan-sessions first to see available projects.'); + } + await profilePipeline.cmdExtractMessages(projectArg, { sessionId, limit }, raw, sessionsPath); + break; + } + + case 'profile-sample': { + const pathIdx = args.indexOf('--path'); + const sessionsPath = pathIdx !== -1 ? args[pathIdx + 1] : null; + const limitIdx = args.indexOf('--limit'); + const limit = limitIdx !== -1 ? parseInt(args[limitIdx + 1], 10) : 150; + const maxPerIdx = args.indexOf('--max-per-project'); + const maxPerProject = maxPerIdx !== -1 ? parseInt(args[maxPerIdx + 1], 10) : null; + const maxCharsIdx = args.indexOf('--max-chars'); + const maxChars = maxCharsIdx !== -1 ? parseInt(args[maxCharsIdx + 1], 10) : 500; + await profilePipeline.cmdProfileSample(sessionsPath, { limit, maxPerProject, maxChars }, raw); + break; + } + + // ─── Profile Output ────────────────────────────────────────────────── + + case 'write-profile': { + const inputIdx = args.indexOf('--input'); + const inputPath = inputIdx !== -1 ? args[inputIdx + 1] : null; + if (!inputPath) error('--input is required'); + const outputIdx = args.indexOf('--output'); + const outputPath = outputIdx !== -1 ? args[outputIdx + 1] : null; + profileOutput.cmdWriteProfile(cwd, { input: inputPath, output: outputPath }, raw); + break; + } + + case 'profile-questionnaire': { + const answersIdx = args.indexOf('--answers'); + const answers = answersIdx !== -1 ? args[answersIdx + 1] : null; + profileOutput.cmdProfileQuestionnaire({ answers }, raw); + break; + } + + case 'generate-dev-preferences': { + const analysisIdx = args.indexOf('--analysis'); + const analysisPath = analysisIdx !== -1 ? args[analysisIdx + 1] : null; + const outputIdx = args.indexOf('--output'); + const outputPath = outputIdx !== -1 ? args[outputIdx + 1] : null; + const stackIdx = args.indexOf('--stack'); + const stack = stackIdx !== -1 ? args[stackIdx + 1] : null; + profileOutput.cmdGenerateDevPreferences(cwd, { analysis: analysisPath, output: outputPath, stack }, raw); + break; + } + + case 'generate-OpenCode-profile': { + const analysisIdx = args.indexOf('--analysis'); + const analysisPath = analysisIdx !== -1 ? args[analysisIdx + 1] : null; + const outputIdx = args.indexOf('--output'); + const outputPath = outputIdx !== -1 ? args[outputIdx + 1] : null; + const globalFlag = args.includes('--global'); + profileOutput.cmdGenerateClaudeProfile(cwd, { analysis: analysisPath, output: outputPath, global: globalFlag }, raw); + break; + } + + case 'generate-OpenCode-md': { + const outputIdx = args.indexOf('--output'); + const outputPath = outputIdx !== -1 ? args[outputIdx + 1] : null; + const autoFlag = args.includes('--auto'); + const forceFlag = args.includes('--force'); + profileOutput.cmdGenerateClaudeMd(cwd, { output: outputPath, auto: autoFlag, force: forceFlag }, raw); + break; + } + + case 'workstream': { + const subcommand = args[1]; + if (subcommand === 'create') { + const migrateNameIdx = args.indexOf('--migrate-name'); + const noMigrate = args.includes('--no-migrate'); + workstream.cmdWorkstreamCreate(cwd, args[2], { + migrate: !noMigrate, + migrateName: migrateNameIdx !== -1 ? args[migrateNameIdx + 1] : null, + }, raw); + } else if (subcommand === 'list') { + workstream.cmdWorkstreamList(cwd, raw); + } else if (subcommand === 'status') { + workstream.cmdWorkstreamStatus(cwd, args[2], raw); + } else if (subcommand === 'complete') { + workstream.cmdWorkstreamComplete(cwd, args[2], {}, raw); + } else if (subcommand === 'set') { + workstream.cmdWorkstreamSet(cwd, args[2], raw); + } else if (subcommand === 'get') { + workstream.cmdWorkstreamGet(cwd, raw); + } else if (subcommand === 'progress') { + workstream.cmdWorkstreamProgress(cwd, raw); + } else { + error('Unknown workstream subcommand. Available: create, list, status, complete, set, get, progress'); + } + break; + } + default: error(`Unknown command: ${command}`); } diff --git a/gsd-opencode/get-shit-done/bin/lib/commands.cjs b/gsd-opencode/get-shit-done/bin/lib/commands.cjs index 576e709..97e72a5 100644 --- a/gsd-opencode/get-shit-done/bin/lib/commands.cjs +++ b/gsd-opencode/get-shit-done/bin/lib/commands.cjs @@ -4,8 +4,9 @@ const fs = require('fs'); const path = require('path'); const { execSync } = require('child_process'); -const { safeReadFile, loadConfig, isGitIgnored, execGit, normalizePhaseName, comparePhaseNum, getArchivedPhaseDirs, generateSlugInternal, getMilestoneInfo, resolveModelInternal, MODEL_PROFILES, toPosixPath, output, error, findPhaseInternal } = require('./core.cjs'); +const { safeReadFile, loadConfig, isGitIgnored, execGit, normalizePhaseName, comparePhaseNum, getArchivedPhaseDirs, generateSlugInternal, getMilestoneInfo, getMilestonePhaseFilter, resolveModelInternal, stripShippedMilestones, extractCurrentMilestone, planningDir, planningPaths, toPosixPath, output, error, findPhaseInternal, extractOneLinerFromBody, getRoadmapPhaseInternal } = require('./core.cjs'); const { extractFrontmatter } = require('./frontmatter.cjs'); +const { MODEL_PROFILES } = require('./model-profiles.cjs'); function cmdGenerateSlug(text, raw) { if (!text) { @@ -42,7 +43,7 @@ function cmdCurrentTimestamp(format, raw) { } function cmdListTodos(cwd, area, raw) { - const pendingDir = path.join(cwd, '.planning', 'todos', 'pending'); + const pendingDir = path.join(planningDir(cwd), 'todos', 'pending'); let count = 0; const todos = []; @@ -68,11 +69,11 @@ function cmdListTodos(cwd, area, raw) { created: createdMatch ? createdMatch[1].trim() : 'unknown', title: titleMatch ? titleMatch[1].trim() : 'Untitled', area: todoArea, - path: toPosixPath(path.join('.planning', 'todos', 'pending', file)), + path: toPosixPath(path.relative(cwd, path.join(pendingDir, file))), }); - } catch {} + } catch { /* intentionally empty */ } } - } catch {} + } catch { /* intentionally empty */ } const result = { count, todos }; output(result, raw, count.toString()); @@ -83,6 +84,11 @@ function cmdVerifyPathExists(cwd, targetPath, raw) { error('path required for verification'); } + // Reject null bytes and validate path does not contain traversal attempts + if (targetPath.includes('\0')) { + error('path contains null bytes'); + } + const fullPath = path.isAbsolute(targetPath) ? targetPath : path.join(cwd, targetPath); try { @@ -97,7 +103,7 @@ function cmdVerifyPathExists(cwd, targetPath, raw) { } function cmdHistoryDigest(cwd, raw) { - const phasesDir = path.join(cwd, '.planning', 'phases'); + const phasesDir = planningPaths(cwd).phases; const digest = { phases: {}, decisions: [], tech_stack: new Set() }; // Collect all phase directories: archived + current @@ -119,7 +125,7 @@ function cmdHistoryDigest(cwd, raw) { for (const dir of currentDirs) { allPhaseDirs.push({ name: dir, fullPath: path.join(phasesDir, dir), milestone: null }); } - } catch {} + } catch { /* intentionally empty */ } } if (allPhaseDirs.length === 0) { @@ -213,11 +219,18 @@ function cmdResolveModel(cwd, agentType, raw) { output(result, raw, model); } -function cmdCommit(cwd, message, files, raw, amend) { +function cmdCommit(cwd, message, files, raw, amend, noVerify) { if (!message && !amend) { error('commit message required'); } + // Sanitize commit message: strip invisible chars and injection markers + // that could hijack agent context when commit messages are read back + if (message) { + const { sanitizeForPrompt } = require('./security.cjs'); + message = sanitizeForPrompt(message); + } + const config = loadConfig(cwd); // Check commit_docs config @@ -234,14 +247,58 @@ function cmdCommit(cwd, message, files, raw, amend) { return; } + // Ensure branching strategy branch exists before first commit (#1278). + // Pre-execution workflows (discuss, plan, research) commit artifacts but the branch + // was previously only created during execute-phase — too late. + if (config.branching_strategy && config.branching_strategy !== 'none') { + let branchName = null; + if (config.branching_strategy === 'phase') { + // Determine which phase we're committing for from the file paths + const phaseMatch = (files || []).join(' ').match(/(\d+)-/); + if (phaseMatch) { + const phaseNum = phaseMatch[1]; + const phaseInfo = findPhaseInternal(cwd, phaseNum); + if (phaseInfo) { + branchName = config.phase_branch_template + .replace('{phase}', phaseInfo.phase_number) + .replace('{slug}', phaseInfo.phase_slug || 'phase'); + } + } + } else if (config.branching_strategy === 'milestone') { + const milestone = getMilestoneInfo(cwd); + if (milestone && milestone.version) { + branchName = config.milestone_branch_template + .replace('{milestone}', milestone.version) + .replace('{slug}', generateSlugInternal(milestone.name) || 'milestone'); + } + } + if (branchName) { + const currentBranch = execGit(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']); + if (currentBranch.exitCode === 0 && currentBranch.stdout.trim() !== branchName) { + // Create branch if it doesn't exist, or switch to it if it does + const create = execGit(cwd, ['checkout', '-b', branchName]); + if (create.exitCode !== 0) { + execGit(cwd, ['checkout', branchName]); + } + } + } + } + // Stage files const filesToStage = files && files.length > 0 ? files : ['.planning/']; for (const file of filesToStage) { - execGit(cwd, ['add', file]); + const fullPath = path.join(cwd, file); + if (!fs.existsSync(fullPath)) { + // File was deleted/moved — stage the deletion + execGit(cwd, ['rm', '--cached', '--ignore-unmatch', file]); + } else { + execGit(cwd, ['add', file]); + } } - // Commit + // Commit (--no-verify skips pre-commit hooks, used by parallel executor agents) const commitArgs = amend ? ['commit', '--amend', '--no-edit'] : ['commit', '-m', message]; + if (noVerify) commitArgs.push('--no-verify'); const commitResult = execGit(cwd, commitArgs); if (commitResult.exitCode !== 0) { if (commitResult.stdout.includes('nothing to commit') || commitResult.stderr.includes('nothing to commit')) { @@ -261,6 +318,74 @@ function cmdCommit(cwd, message, files, raw, amend) { output(result, raw, hash || 'committed'); } +function cmdCommitToSubrepo(cwd, message, files, raw) { + if (!message) { + error('commit message required'); + } + + const config = loadConfig(cwd); + const subRepos = config.sub_repos; + + if (!subRepos || subRepos.length === 0) { + error('no sub_repos configured in .planning/config.json'); + } + + if (!files || files.length === 0) { + error('--files required for commit-to-subrepo'); + } + + // Group files by sub-repo prefix + const grouped = {}; + const unmatched = []; + for (const file of files) { + const match = subRepos.find(repo => file.startsWith(repo + '/')); + if (match) { + if (!grouped[match]) grouped[match] = []; + grouped[match].push(file); + } else { + unmatched.push(file); + } + } + + if (unmatched.length > 0) { + process.stderr.write(`Warning: ${unmatched.length} file(s) did not match any sub-repo prefix: ${unmatched.join(', ')}\n`); + } + + const repos = {}; + for (const [repo, repoFiles] of Object.entries(grouped)) { + const repoCwd = path.join(cwd, repo); + + // Stage files (strip sub-repo prefix for paths relative to that repo) + for (const file of repoFiles) { + const relativePath = file.slice(repo.length + 1); + execGit(repoCwd, ['add', relativePath]); + } + + // Commit + const commitResult = execGit(repoCwd, ['commit', '-m', message]); + if (commitResult.exitCode !== 0) { + if (commitResult.stdout.includes('nothing to commit') || commitResult.stderr.includes('nothing to commit')) { + repos[repo] = { committed: false, hash: null, files: repoFiles, reason: 'nothing_to_commit' }; + continue; + } + repos[repo] = { committed: false, hash: null, files: repoFiles, reason: 'error', error: commitResult.stderr }; + continue; + } + + // Get hash + const hashResult = execGit(repoCwd, ['rev-parse', '--short', 'HEAD']); + const hash = hashResult.exitCode === 0 ? hashResult.stdout : null; + repos[repo] = { committed: true, hash, files: repoFiles }; + } + + const result = { + committed: Object.values(repos).some(r => r.committed), + repos, + unmatched: unmatched.length > 0 ? unmatched : undefined, + }; + output(result, raw, Object.entries(repos).map(([r, v]) => `${r}:${v.hash || 'skip'}`).join(' ')); +} + function cmdSummaryExtract(cwd, summaryPath, fields, raw) { if (!summaryPath) { error('summary-path required for summary-extract'); @@ -294,7 +419,7 @@ function cmdSummaryExtract(cwd, summaryPath, fields, raw) { // Build full result const fullResult = { path: summaryPath, - one_liner: fm['one-liner'] || null, + one_liner: fm['one-liner'] || extractOneLinerFromBody(content) || null, key_files: fm['key-files'] || [], tech_added: (fm['tech-stack'] && fm['tech-stack'].added) || [], patterns: fm['patterns-established'] || [], @@ -380,8 +505,8 @@ async function cmdWebsearch(query, options, raw) { } function cmdProgressRender(cwd, format, raw) { - const phasesDir = path.join(cwd, '.planning', 'phases'); - const roadmapPath = path.join(cwd, '.planning', 'ROADMAP.md'); + const phasesDir = planningPaths(cwd).phases; + const roadmapPath = planningPaths(cwd).roadmap; const milestone = getMilestoneInfo(cwd); const phases = []; @@ -411,7 +536,7 @@ function cmdProgressRender(cwd, format, raw) { phases.push({ number: phaseNum, name: phaseName, plans, summaries, status }); } - } catch {} + } catch { /* intentionally empty */ } const percent = totalPlans > 0 ? Math.min(100, Math.round((totalSummaries / totalPlans) * 100)) : 0; @@ -447,13 +572,137 @@ function cmdProgressRender(cwd, format, raw) { } } +/** + * Match pending todos against a phase's goal/name/requirements. + * Returns todos with relevance scores based on keyword, area, and file overlap. + * Used by discuss-phase to surface relevant todos before scope-setting. + */ +function cmdTodoMatchPhase(cwd, phase, raw) { + if (!phase) { error('phase required for todo match-phase'); } + + const pendingDir = path.join(planningDir(cwd), 'todos', 'pending'); + const todos = []; + + // Load pending todos + try { + const files = fs.readdirSync(pendingDir).filter(f => f.endsWith('.md')); + for (const file of files) { + try { + const content = fs.readFileSync(path.join(pendingDir, file), 'utf-8'); + const titleMatch = content.match(/^title:\s*(.+)$/m); + const areaMatch = content.match(/^area:\s*(.+)$/m); + const filesMatch = content.match(/^files:\s*(.+)$/m); + const body = content.replace(/^(title|area|files|created|priority):.*$/gm, '').trim(); + + todos.push({ + file, + title: titleMatch ? titleMatch[1].trim() : 'Untitled', + area: areaMatch ? areaMatch[1].trim() : 'general', + files: filesMatch ? filesMatch[1].trim().split(/[,\s]+/).filter(Boolean) : [], + body: body.slice(0, 200), // first 200 chars for context + }); + } catch {} + } + } catch {} + + if (todos.length === 0) { + output({ phase, matches: [], todo_count: 0 }, raw); + return; + } + + // Load phase goal/name from ROADMAP + const phaseInfo = getRoadmapPhaseInternal(cwd, phase); + const phaseName = phaseInfo ? (phaseInfo.phase_name || '') : ''; + const phaseGoal = phaseInfo ? (phaseInfo.goal || '') : ''; + const phaseSection = phaseInfo ? (phaseInfo.section || '') : ''; + + // Build keyword set from phase name + goal + section text + const phaseText = `${phaseName} ${phaseGoal} ${phaseSection}`.toLowerCase(); + const stopWords = new Set(['the', 'and', 'for', 'with', 'from', 'that', 'this', 'will', 'are', 'was', 'has', 'have', 'been', 'not', 'but', 'all', 'can', 'into', 'each', 'when', 'any', 'use', 'new']); + const phaseKeywords = new Set( + phaseText.split(/[\s\-_/.,;:()\[\]{}|]+/) + .map(w => w.replace(/[^a-z0-9]/g, '')) + .filter(w => w.length > 2 && !stopWords.has(w)) + ); + + // Find phase directory to get expected file paths + const phaseInfoDisk = findPhaseInternal(cwd, phase); + const phasePlans = []; + if (phaseInfoDisk && phaseInfoDisk.found) { + try { + const phaseDir = path.join(cwd, phaseInfoDisk.directory); + const planFiles = fs.readdirSync(phaseDir).filter(f => f.endsWith('-PLAN.md')); + for (const pf of planFiles) { + try { + const planContent = fs.readFileSync(path.join(phaseDir, pf), 'utf-8'); + const fmFiles = planContent.match(/files_modified:\s*\[([^\]]*)\]/); + if (fmFiles) { + phasePlans.push(...fmFiles[1].split(',').map(s => s.trim().replace(/['"]/g, '')).filter(Boolean)); + } + } catch {} + } + } catch {} + } + + // Score each todo for relevance + const matches = []; + for (const todo of todos) { + let score = 0; + const reasons = []; + + // Keyword match: todo title/body terms in phase text + const todoWords = `${todo.title} ${todo.body}`.toLowerCase() + .split(/[\s\-_/.,;:()\[\]{}|]+/) + .map(w => w.replace(/[^a-z0-9]/g, '')) + .filter(w => w.length > 2 && !stopWords.has(w)); + + const matchedKeywords = todoWords.filter(w => phaseKeywords.has(w)); + if (matchedKeywords.length > 0) { + score += Math.min(matchedKeywords.length * 0.2, 0.6); + reasons.push(`keywords: ${[...new Set(matchedKeywords)].slice(0, 5).join(', ')}`); + } + + // Area match: todo area appears in phase text + if (todo.area !== 'general' && phaseText.includes(todo.area.toLowerCase())) { + score += 0.3; + reasons.push(`area: ${todo.area}`); + } + + // File match: todo files overlap with phase plan files + if (todo.files.length > 0 && phasePlans.length > 0) { + const fileOverlap = todo.files.filter(f => + phasePlans.some(pf => pf.includes(f) || f.includes(pf)) + ); + if (fileOverlap.length > 0) { + score += 0.4; + reasons.push(`files: ${fileOverlap.slice(0, 3).join(', ')}`); + } + } + + if (score > 0) { + matches.push({ + file: todo.file, + title: todo.title, + area: todo.area, + score: Math.round(score * 100) / 100, + reasons, + }); + } + } + + // Sort by score descending + matches.sort((a, b) => b.score - a.score); + + output({ phase, matches, todo_count: todos.length }, raw); +} + function cmdTodoComplete(cwd, filename, raw) { if (!filename) { error('filename required for todo complete'); } - const pendingDir = path.join(cwd, '.planning', 'todos', 'pending'); - const completedDir = path.join(cwd, '.planning', 'todos', 'completed'); + const pendingDir = path.join(planningDir(cwd), 'todos', 'pending'); + const completedDir = path.join(planningDir(cwd), 'todos', 'completed'); const sourcePath = path.join(pendingDir, filename); if (!fs.existsSync(sourcePath)) { @@ -511,11 +760,11 @@ function cmdScaffold(cwd, type, options, raw) { } const slug = generateSlugInternal(name); const dirName = `${padded}-${slug}`; - const phasesParent = path.join(cwd, '.planning', 'phases'); + const phasesParent = planningPaths(cwd).phases; fs.mkdirSync(phasesParent, { recursive: true }); const dirPath = path.join(phasesParent, dirName); fs.mkdirSync(dirPath, { recursive: true }); - output({ created: true, directory: `.planning/phases/${dirName}`, path: dirPath }, raw, dirPath); + output({ created: true, directory: toPosixPath(path.relative(cwd, dirPath)), path: dirPath }, raw, dirPath); return; } default: @@ -532,6 +781,165 @@ function cmdScaffold(cwd, type, options, raw) { output({ created: true, path: relPath }, raw, relPath); } +function cmdStats(cwd, format, raw) { + const phasesDir = planningPaths(cwd).phases; + const roadmapPath = planningPaths(cwd).roadmap; + const reqPath = planningPaths(cwd).requirements; + const statePath = planningPaths(cwd).state; + const milestone = getMilestoneInfo(cwd); + const isDirInMilestone = getMilestonePhaseFilter(cwd); + + // Phase & plan stats (reuse progress pattern) + const phasesByNumber = new Map(); + let totalPlans = 0; + let totalSummaries = 0; + + try { + const roadmapContent = extractCurrentMilestone(fs.readFileSync(roadmapPath, 'utf-8'), cwd); + const headingPattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:\s*([^\n]+)/gi; + let match; + while ((match = headingPattern.exec(roadmapContent)) !== null) { + phasesByNumber.set(match[1], { + number: match[1], + name: match[2].replace(/\(INSERTED\)/i, '').trim(), + plans: 0, + summaries: 0, + status: 'Not Started', + }); + } + } catch { /* intentionally empty */ } + + try { + const entries = fs.readdirSync(phasesDir, { withFileTypes: true }); + const dirs = entries + .filter(e => e.isDirectory()) + .map(e => e.name) + .filter(isDirInMilestone) + .sort((a, b) => comparePhaseNum(a, b)); + + for (const dir of dirs) { + const dm = dir.match(/^(\d+[A-Z]?(?:\.\d+)*)-?(.*)/i); + const phaseNum = dm ? dm[1] : dir; + const phaseName = dm && dm[2] ? dm[2].replace(/-/g, ' ') : ''; + const phaseFiles = fs.readdirSync(path.join(phasesDir, dir)); + const plans = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md').length; + const summaries = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md').length; + + totalPlans += plans; + totalSummaries += summaries; + + let status; + if (plans === 0) status = 'Not Started'; + else if (summaries >= plans) status = 'Complete'; + else if (summaries > 0) status = 'In Progress'; + else status = 'Planned'; + + const existing = phasesByNumber.get(phaseNum); + phasesByNumber.set(phaseNum, { + number: phaseNum, + name: existing?.name || phaseName, + plans, + summaries, + status, + }); + } + } catch { /* intentionally empty */ } + + const phases = [...phasesByNumber.values()].sort((a, b) => comparePhaseNum(a.number, b.number)); + const completedPhases = phases.filter(p => p.status === 'Complete').length; + const planPercent = totalPlans > 0 ? Math.min(100, Math.round((totalSummaries / totalPlans) * 100)) : 0; + const percent = phases.length > 0 ? Math.min(100, Math.round((completedPhases / phases.length) * 100)) : 0; + + // Requirements stats + let requirementsTotal = 0; + let requirementsComplete = 0; + try { + if (fs.existsSync(reqPath)) { + const reqContent = fs.readFileSync(reqPath, 'utf-8'); + const checked = reqContent.match(/^- \[x\] \*\*/gm); + const unchecked = reqContent.match(/^- \[ \] \*\*/gm); + requirementsComplete = checked ? checked.length : 0; + requirementsTotal = requirementsComplete + (unchecked ? unchecked.length : 0); + } + } catch { /* intentionally empty */ } + + // Last activity from STATE.md + let lastActivity = null; + try { + if (fs.existsSync(statePath)) { + const stateContent = fs.readFileSync(statePath, 'utf-8'); + const activityMatch = stateContent.match(/^last_activity:\s*(.+)$/im) + || stateContent.match(/\*\*Last Activity:\*\*\s*(.+)/i) + || stateContent.match(/^Last Activity:\s*(.+)$/im) + || stateContent.match(/^Last activity:\s*(.+)$/im); + if (activityMatch) lastActivity = activityMatch[1].trim(); + } + } catch { /* intentionally empty */ } + + // Git stats + let gitCommits = 0; + let gitFirstCommitDate = null; + const commitCount = execGit(cwd, ['rev-list', '--count', 'HEAD']); + if (commitCount.exitCode === 0) { + gitCommits = parseInt(commitCount.stdout, 10) || 0; + } + const rootHash = execGit(cwd, ['rev-list', '--max-parents=0', 'HEAD']); + if (rootHash.exitCode === 0 && rootHash.stdout) { + const firstCommit = rootHash.stdout.split('\n')[0].trim(); + const firstDate = execGit(cwd, ['show', '-s', '--format=%as', firstCommit]); + if (firstDate.exitCode === 0) { + gitFirstCommitDate = firstDate.stdout || null; + } + } + + const result = { + milestone_version: milestone.version, + milestone_name: milestone.name, + phases, + phases_completed: completedPhases, + phases_total: phases.length, + total_plans: totalPlans, + total_summaries: totalSummaries, + percent, + plan_percent: planPercent, + requirements_total: requirementsTotal, + requirements_complete: requirementsComplete, + git_commits: gitCommits, + git_first_commit_date: gitFirstCommitDate, + last_activity: lastActivity, + }; + + if (format === 'table') { + const barWidth = 10; + const filled = Math.round((percent / 100) * barWidth); + const bar = '\u2588'.repeat(filled) + '\u2591'.repeat(barWidth - filled); + let out = `# ${milestone.version} ${milestone.name} \u2014 Statistics\n\n`; + out += `**Progress:** [${bar}] ${completedPhases}/${phases.length} phases (${percent}%)\n`; + if (totalPlans > 0) { + out += `**Plans:** ${totalSummaries}/${totalPlans} complete (${planPercent}%)\n`; + } + out += `**Phases:** ${completedPhases}/${phases.length} complete\n`; + if (requirementsTotal > 0) { + out += `**Requirements:** ${requirementsComplete}/${requirementsTotal} complete\n`; + } + out += '\n'; + out += `| Phase | Name | Plans | Completed | Status |\n`; + out += `|-------|------|-------|-----------|--------|\n`; + for (const p of phases) { + out += `| ${p.number} | ${p.name} | ${p.plans} | ${p.summaries} | ${p.status} |\n`; + } + if (gitCommits > 0) { + out += `\n**Git:** ${gitCommits} commits`; + if (gitFirstCommitDate) out += ` (since ${gitFirstCommitDate})`; + out += '\n'; + } + if (lastActivity) out += `**Last activity:** ${lastActivity}\n`; + output({ rendered: out }, raw, out); + } else { + output(result, raw); + } +} + module.exports = { cmdGenerateSlug, cmdCurrentTimestamp, @@ -540,9 +948,12 @@ module.exports = { cmdHistoryDigest, cmdResolveModel, cmdCommit, + cmdCommitToSubrepo, cmdSummaryExtract, cmdWebsearch, cmdProgressRender, cmdTodoComplete, + cmdTodoMatchPhase, cmdScaffold, + cmdStats, }; diff --git a/gsd-opencode/get-shit-done/bin/lib/config.cjs b/gsd-opencode/get-shit-done/bin/lib/config.cjs index da0da4d..9bf8c77 100644 --- a/gsd-opencode/get-shit-done/bin/lib/config.cjs +++ b/gsd-opencode/get-shit-done/bin/lib/config.cjs @@ -4,32 +4,81 @@ const fs = require('fs'); const path = require('path'); -const { output, error } = require('./core.cjs'); +const { output, error, planningRoot } = require('./core.cjs'); +const { + VALID_PROFILES, + getAgentToModelMapForProfile, + formatAgentToModelMapAsTable, +} = require('./model-profiles.cjs'); -function cmdConfigEnsureSection(cwd, raw) { - const configPath = path.join(cwd, '.planning', 'config.json'); - const planningDir = path.join(cwd, '.planning'); +const VALID_CONFIG_KEYS = new Set([ + 'mode', 'granularity', 'parallelization', 'commit_docs', 'model_profile', + 'search_gitignored', 'brave_search', 'firecrawl', 'exa_search', + 'workflow.research', 'workflow.plan_check', 'workflow.verifier', + 'workflow.nyquist_validation', 'workflow.ui_phase', 'workflow.ui_safety_gate', + 'workflow.auto_advance', 'workflow.node_repair', 'workflow.node_repair_budget', + 'workflow.text_mode', + 'workflow.research_before_questions', + 'workflow.discuss_mode', + 'workflow.skip_discuss', + 'workflow._auto_chain_active', + 'git.branching_strategy', 'git.phase_branch_template', 'git.milestone_branch_template', 'git.quick_branch_template', + 'planning.commit_docs', 'planning.search_gitignored', + 'hooks.context_warnings', +]); - // Ensure .planning directory exists - try { - if (!fs.existsSync(planningDir)) { - fs.mkdirSync(planningDir, { recursive: true }); - } - } catch (err) { - error('Failed to create .planning directory: ' + err.message); - } +/** + * Check whether a config key path is valid. + * Supports exact matches from VALID_CONFIG_KEYS plus dynamic patterns + * like `agent_skills.` where the sub-key is freeform. + */ +function isValidConfigKey(keyPath) { + if (VALID_CONFIG_KEYS.has(keyPath)) return true; + // Allow agent_skills. with any agent type string + if (/^agent_skills\.[a-zA-Z0-9_-]+$/.test(keyPath)) return true; + return false; +} - // Check if config already exists - if (fs.existsSync(configPath)) { - const result = { created: false, reason: 'already_exists' }; - output(result, raw, 'exists'); - return; +const CONFIG_KEY_SUGGESTIONS = { + 'workflow.nyquist_validation_enabled': 'workflow.nyquist_validation', + 'agents.nyquist_validation_enabled': 'workflow.nyquist_validation', + 'nyquist.validation_enabled': 'workflow.nyquist_validation', + 'hooks.research_questions': 'workflow.research_before_questions', + 'workflow.research_questions': 'workflow.research_before_questions', +}; + +function validateKnownConfigKeyPath(keyPath) { + const suggested = CONFIG_KEY_SUGGESTIONS[keyPath]; + if (suggested) { + error(`Unknown config key: ${keyPath}. Did you mean ${suggested}?`); } +} - // Detect Brave Search API key availability +/** + * Build a fully-materialized config object for a new project. + * + * Merges (increasing priority): + * 1. Hardcoded defaults — every key that loadConfig() resolves, plus mode/granularity + * 2. User-level defaults from ~/.gsd/defaults.json (if present) + * 3. userChoices — the settings the user explicitly selected during /gsd-new-project + * + * Uses the canonical `git` namespace for branching keys (consistent with VALID_CONFIG_KEYS + * and the settings workflow). loadConfig() handles both flat and nested formats, so this + * is backward-compatible with existing projects that have flat keys. + * + * Returns a plain object — does NOT write any files. + */ +function buildNewProjectConfig(userChoices) { + const choices = userChoices || {}; const homedir = require('os').homedir(); + + // Detect API key availability const braveKeyFile = path.join(homedir, '.gsd', 'brave_api_key'); const hasBraveSearch = !!(process.env.BRAVE_API_KEY || fs.existsSync(braveKeyFile)); + const firecrawlKeyFile = path.join(homedir, '.gsd', 'firecrawl_api_key'); + const hasFirecrawl = !!(process.env.FIRECRAWL_API_KEY || fs.existsSync(firecrawlKeyFile)); + const exaKeyFile = path.join(homedir, '.gsd', 'exa_api_key'); + const hasExaSearch = !!(process.env.EXA_API_KEY || fs.existsSync(exaKeyFile)); // Load user-level defaults from ~/.gsd/defaults.json if available const globalDefaultsPath = path.join(homedir, '.gsd', 'defaults.json'); @@ -42,57 +91,184 @@ function cmdConfigEnsureSection(cwd, raw) { const depthToGranularity = { quick: 'coarse', standard: 'standard', comprehensive: 'fine' }; userDefaults.granularity = depthToGranularity[userDefaults.depth] || userDefaults.depth; delete userDefaults.depth; - try { fs.writeFileSync(globalDefaultsPath, JSON.stringify(userDefaults, null, 2), 'utf-8'); } catch {} + try { + fs.writeFileSync(globalDefaultsPath, JSON.stringify(userDefaults, null, 2), 'utf-8'); + } catch { /* intentionally empty */ } } } - } catch (err) { - // Ignore malformed global defaults, fall back to hardcoded + } catch { + // Ignore malformed global defaults } - // Create default config (user-level defaults override hardcoded defaults) const hardcoded = { model_profile: 'balanced', commit_docs: true, + parallelization: true, search_gitignored: false, - branching_strategy: 'none', - phase_branch_template: 'gsd/phase-{phase}-{slug}', - milestone_branch_template: 'gsd/{milestone}-{slug}', + brave_search: hasBraveSearch, + firecrawl: hasFirecrawl, + exa_search: hasExaSearch, + git: { + branching_strategy: 'none', + phase_branch_template: 'gsd/phase-{phase}-{slug}', + milestone_branch_template: 'gsd/{milestone}-{slug}', + quick_branch_template: null, + }, workflow: { research: true, plan_check: true, verifier: true, nyquist_validation: true, + auto_advance: false, + node_repair: true, + node_repair_budget: 2, + ui_phase: true, + ui_safety_gate: true, + text_mode: false, + research_before_questions: false, + discuss_mode: 'discuss', + skip_discuss: false, }, - parallelization: true, - brave_search: hasBraveSearch, + hooks: { + context_warnings: true, + }, + agent_skills: {}, }; - const defaults = { + + // Three-level deep merge: hardcoded <- userDefaults <- choices + return { ...hardcoded, ...userDefaults, - workflow: { ...hardcoded.workflow, ...(userDefaults.workflow || {}) }, + ...choices, + git: { + ...hardcoded.git, + ...(userDefaults.git || {}), + ...(choices.git || {}), + }, + workflow: { + ...hardcoded.workflow, + ...(userDefaults.workflow || {}), + ...(choices.workflow || {}), + }, + hooks: { + ...hardcoded.hooks, + ...(userDefaults.hooks || {}), + ...(choices.hooks || {}), + }, + agent_skills: { + ...hardcoded.agent_skills, + ...(userDefaults.agent_skills || {}), + ...(choices.agent_skills || {}), + }, }; +} + +/** + * Command: create a fully-materialized .planning/config.json for a new project. + * + * Accepts user-chosen settings as a JSON string (the keys the user explicitly + * configured during /gsd-new-project). All remaining keys are filled from + * hardcoded defaults and optional ~/.gsd/defaults.json. + * + * Idempotent: if config.json already exists, returns { created: false }. + */ +function cmdConfigNewProject(cwd, choicesJson, raw) { + const planningBase = planningRoot(cwd); + const configPath = path.join(planningBase, 'config.json'); + // Idempotent: don't overwrite existing config + if (fs.existsSync(configPath)) { + output({ created: false, reason: 'already_exists' }, raw, 'exists'); + return; + } + + // Parse user choices + let userChoices = {}; + if (choicesJson && choicesJson.trim() !== '') { + try { + userChoices = JSON.parse(choicesJson); + } catch (err) { + error('Invalid JSON for config-new-project: ' + err.message); + } + } + + // Ensure .planning directory exists try { - fs.writeFileSync(configPath, JSON.stringify(defaults, null, 2), 'utf-8'); - const result = { created: true, path: '.planning/config.json' }; - output(result, raw, 'created'); + if (!fs.existsSync(planningBase)) { + fs.mkdirSync(planningBase, { recursive: true }); + } } catch (err) { - error('Failed to create config.json: ' + err.message); + error('Failed to create .planning directory: ' + err.message); + } + + const config = buildNewProjectConfig(userChoices); + + try { + fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8'); + output({ created: true, path: '.planning/config.json' }, raw, 'created'); + } catch (err) { + error('Failed to write config.json: ' + err.message); } } -function cmdConfigSet(cwd, keyPath, value, raw) { - const configPath = path.join(cwd, '.planning', 'config.json'); +/** + * Ensures the config file exists (creates it if needed). + * + * Does not call `output()`, so can be used as one step in a command without triggering `exit(0)` in + * the happy path. But note that `error()` will still `exit(1)` out of the process. + */ +function ensureConfigFile(cwd) { + const planningBase = planningRoot(cwd); + const configPath = path.join(planningBase, 'config.json'); - if (!keyPath) { - error('Usage: config-set '); + // Ensure .planning directory exists + try { + if (!fs.existsSync(planningBase)) { + fs.mkdirSync(planningBase, { recursive: true }); + } + } catch (err) { + error('Failed to create .planning directory: ' + err.message); } - // Parse value (handle booleans and numbers) - let parsedValue = value; - if (value === 'true') parsedValue = true; - else if (value === 'false') parsedValue = false; - else if (!isNaN(value) && value !== '') parsedValue = Number(value); + // Check if config already exists + if (fs.existsSync(configPath)) { + return { created: false, reason: 'already_exists' }; + } + + const config = buildNewProjectConfig({}); + + try { + fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8'); + return { created: true, path: '.planning/config.json' }; + } catch (err) { + error('Failed to create config.json: ' + err.message); + } +} + +/** + * Command to ensure the config file exists (creates it if needed). + * + * Note that this exits the process (via `output()`) even in the happy path; use + * `ensureConfigFile()` directly if you need to avoid this. + */ +function cmdConfigEnsureSection(cwd, raw) { + const ensureConfigFileResult = ensureConfigFile(cwd); + if (ensureConfigFileResult.created) { + output(ensureConfigFileResult, raw, 'created'); + } else { + output(ensureConfigFileResult, raw, 'exists'); + } +} + +/** + * Sets a value in the config file, allowing nested values via dot notation (e.g., + * "workflow.research"). + * + * Does not call `output()`, so can be used as one step in a command without triggering `exit(0)` in + * the happy path. But note that `error()` will still `exit(1)` out of the process. + */ +function setConfigValue(cwd, keyPath, parsedValue) { + const configPath = path.join(planningRoot(cwd), 'config.json'); // Load existing config or start with empty object let config = {}; @@ -114,20 +290,51 @@ function cmdConfigSet(cwd, keyPath, value, raw) { } current = current[key]; } + const previousValue = current[keys[keys.length - 1]]; // Capture previous value before overwriting current[keys[keys.length - 1]] = parsedValue; // write back try { fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8'); - const result = { updated: true, key: keyPath, value: parsedValue }; - output(result, raw, `${keyPath}=${parsedValue}`); + return { updated: true, key: keyPath, value: parsedValue, previousValue }; } catch (err) { error('Failed to write config.json: ' + err.message); } } +/** + * Command to set a value in the config file, allowing nested values via dot notation (e.g., + * "workflow.research"). + * + * Note that this exits the process (via `output()`) even in the happy path; use `setConfigValue()` + * directly if you need to avoid this. + */ +function cmdConfigSet(cwd, keyPath, value, raw) { + if (!keyPath) { + error('Usage: config-set '); + } + + validateKnownConfigKeyPath(keyPath); + + if (!isValidConfigKey(keyPath)) { + error(`Unknown config key: "${keyPath}". Valid keys: ${[...VALID_CONFIG_KEYS].sort().join(', ')}, agent_skills.`); + } + + // Parse value (handle booleans, numbers, and JSON arrays/objects) + let parsedValue = value; + if (value === 'true') parsedValue = true; + else if (value === 'false') parsedValue = false; + else if (!isNaN(value) && value !== '') parsedValue = Number(value); + else if (typeof value === 'string' && (value.startsWith('[') || value.startsWith('{'))) { + try { parsedValue = JSON.parse(value); } catch { /* keep as string */ } + } + + const setConfigValueResult = setConfigValue(cwd, keyPath, parsedValue); + output(setConfigValueResult, raw, `${keyPath}=${parsedValue}`); +} + function cmdConfigGet(cwd, keyPath, raw) { - const configPath = path.join(cwd, '.planning', 'config.json'); + const configPath = path.join(planningRoot(cwd), 'config.json'); if (!keyPath) { error('Usage: config-get '); @@ -162,8 +369,74 @@ function cmdConfigGet(cwd, keyPath, raw) { output(current, raw, String(current)); } +/** + * Command to set the model profile in the config file. + * + * Note that this exits the process (via `output()`) even in the happy path. + */ +function cmdConfigSetModelProfile(cwd, profile, raw) { + if (!profile) { + error(`Usage: config-set-model-profile <${VALID_PROFILES.join('|')}>`); + } + + const normalizedProfile = profile.toLowerCase().trim(); + if (!VALID_PROFILES.includes(normalizedProfile)) { + error(`Invalid profile '${profile}'. Valid profiles: ${VALID_PROFILES.join(', ')}`); + } + + // Ensure config exists (create if needed) + ensureConfigFile(cwd); + + // Set the model profile in the config + const { previousValue } = setConfigValue(cwd, 'model_profile', normalizedProfile, raw); + const previousProfile = previousValue || 'balanced'; + + // Build result value / message and return + const agentToModelMap = getAgentToModelMapForProfile(normalizedProfile); + const result = { + updated: true, + profile: normalizedProfile, + previousProfile, + agentToModelMap, + }; + const rawValue = getCmdConfigSetModelProfileResultMessage( + normalizedProfile, + previousProfile, + agentToModelMap + ); + output(result, raw, rawValue); +} + +/** + * Returns the message to display for the result of the `config-set-model-profile` command when + * displaying raw output. + */ +function getCmdConfigSetModelProfileResultMessage( + normalizedProfile, + previousProfile, + agentToModelMap +) { + const agentToModelTable = formatAgentToModelMapAsTable(agentToModelMap); + const didChange = previousProfile !== normalizedProfile; + const paragraphs = didChange + ? [ + `✓ Model profile set to: ${normalizedProfile} (was: ${previousProfile})`, + 'Agents will now use:', + agentToModelTable, + 'Next spawned agents will use the new profile.', + ] + : [ + `✓ Model profile is already set to: ${normalizedProfile}`, + 'Agents are using:', + agentToModelTable, + ]; + return paragraphs.join('\n\n'); +} + module.exports = { cmdConfigEnsureSection, cmdConfigSet, cmdConfigGet, + cmdConfigSetModelProfile, + cmdConfigNewProject, }; diff --git a/gsd-opencode/get-shit-done/bin/lib/core.cjs b/gsd-opencode/get-shit-done/bin/lib/core.cjs index 5a1e4a3..60476cf 100644 --- a/gsd-opencode/get-shit-done/bin/lib/core.cjs +++ b/gsd-opencode/get-shit-done/bin/lib/core.cjs @@ -4,7 +4,8 @@ const fs = require('fs'); const path = require('path'); -const { execSync } = require('child_process'); +const { execSync, execFileSync, spawnSync } = require('child_process'); +const { MODEL_PROFILES } = require('./model-profiles.cjs'); // ─── Path helpers ──────────────────────────────────────────────────────────── @@ -13,45 +14,173 @@ function toPosixPath(p) { return p.split(path.sep).join('/'); } -// ─── Model Profile Table ───────────────────────────────────────────────────── - -const MODEL_PROFILES = { - 'gsd-planner': { quality: 'opus', balanced: 'opus', budget: 'sonnet' }, - 'gsd-roadmapper': { quality: 'opus', balanced: 'sonnet', budget: 'sonnet' }, - 'gsd-executor': { quality: 'opus', balanced: 'sonnet', budget: 'sonnet' }, - 'gsd-phase-researcher': { quality: 'opus', balanced: 'sonnet', budget: 'haiku' }, - 'gsd-project-researcher': { quality: 'opus', balanced: 'sonnet', budget: 'haiku' }, - 'gsd-research-synthesizer': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' }, - 'gsd-debugger': { quality: 'opus', balanced: 'sonnet', budget: 'sonnet' }, - 'gsd-codebase-mapper': { quality: 'sonnet', balanced: 'haiku', budget: 'haiku' }, - 'gsd-verifier': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' }, - 'gsd-plan-checker': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' }, - 'gsd-integration-checker': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' }, - 'gsd-nyquist-auditor': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' }, -}; +/** + * Scan immediate child directories for separate git repos. + * Returns a sorted array of directory names that have their own `.git`. + * Excludes hidden directories and node_modules. + */ +function detectSubRepos(cwd) { + const results = []; + try { + const entries = fs.readdirSync(cwd, { withFileTypes: true }); + for (const entry of entries) { + if (!entry.isDirectory()) continue; + if (entry.name.startsWith('.') || entry.name === 'node_modules') continue; + const gitPath = path.join(cwd, entry.name, '.git'); + try { + if (fs.existsSync(gitPath)) { + results.push(entry.name); + } + } catch {} + } + } catch {} + return results.sort(); +} + +/** + * Walk up from `startDir` to find the project root that owns `.planning/`. + * + * In multi-repo workspaces, OpenCode may open inside a sub-repo (e.g. `backend/`) + * instead of the project root. This function prevents `.planning/` from being + * created inside the sub-repo by locating the nearest ancestor that already has + * a `.planning/` directory. + * + * Detection strategy (checked in order for each ancestor): + * 1. Parent has `.planning/config.json` with `sub_repos` listing this directory + * 2. Parent has `.planning/config.json` with `multiRepo: true` (legacy format) + * 3. Parent has `.planning/` and current dir has its own `.git` (heuristic) + * + * Returns `startDir` unchanged when no ancestor `.planning/` is found (first-run + * or single-repo projects). + */ +function findProjectRoot(startDir) { + const resolved = path.resolve(startDir); + const root = path.parse(resolved).root; + const homedir = require('os').homedir(); + + // If startDir already contains .planning/, it IS the project root. + // Do not walk up to a parent workspace that also has .planning/ (#1362). + const ownPlanning = path.join(resolved, '.planning'); + if (fs.existsSync(ownPlanning) && fs.statSync(ownPlanning).isDirectory()) { + return startDir; + } + + // Check if startDir or any of its ancestors (up to AND including the + // candidate project root) contains a .git directory. This handles both + // `backend/` (direct sub-repo) and `backend/src/modules/` (nested inside), + // as well as the common case where .git lives at the same level as .planning/. + function isInsideGitRepo(candidateParent) { + let d = resolved; + while (d !== root) { + if (fs.existsSync(path.join(d, '.git'))) return true; + if (d === candidateParent) break; + d = path.dirname(d); + } + return false; + } + + let dir = resolved; + while (dir !== root) { + const parent = path.dirname(dir); + if (parent === dir) break; // filesystem root + if (parent === homedir) break; // never go above home + + const parentPlanning = path.join(parent, '.planning'); + if (fs.existsSync(parentPlanning) && fs.statSync(parentPlanning).isDirectory()) { + const configPath = path.join(parentPlanning, 'config.json'); + try { + const config = JSON.parse(fs.readFileSync(configPath, 'utf-8')); + const subRepos = config.sub_repos || config.planning?.sub_repos || []; + + // Check explicit sub_repos list + if (Array.isArray(subRepos) && subRepos.length > 0) { + const relPath = path.relative(parent, resolved); + const topSegment = relPath.split(path.sep)[0]; + if (subRepos.includes(topSegment)) { + return parent; + } + } + + // Check legacy multiRepo flag + if (config.multiRepo === true && isInsideGitRepo(parent)) { + return parent; + } + } catch { + // config.json missing or malformed — fall back to .git heuristic + } + + // Heuristic: parent has .planning/ and we're inside a git repo + if (isInsideGitRepo(parent)) { + return parent; + } + } + dir = parent; + } + return startDir; +} // ─── Output helpers ─────────────────────────────────────────────────────────── +/** + * Remove stale gsd-* temp files/dirs older than maxAgeMs (default: 5 minutes). + * Runs opportunistically before each new temp file write to prevent unbounded accumulation. + * @param {string} prefix - filename prefix to match (e.g., 'gsd-') + * @param {object} opts + * @param {number} opts.maxAgeMs - max age in ms before removal (default: 5 min) + * @param {boolean} opts.dirsOnly - if true, only remove directories (default: false) + */ +function reapStaleTempFiles(prefix = 'gsd-', { maxAgeMs = 5 * 60 * 1000, dirsOnly = false } = {}) { + try { + const tmpDir = require('os').tmpdir(); + const now = Date.now(); + const entries = fs.readdirSync(tmpDir); + for (const entry of entries) { + if (!entry.startsWith(prefix)) continue; + const fullPath = path.join(tmpDir, entry); + try { + const stat = fs.statSync(fullPath); + if (now - stat.mtimeMs > maxAgeMs) { + if (stat.isDirectory()) { + fs.rmSync(fullPath, { recursive: true, force: true }); + } else if (!dirsOnly) { + fs.unlinkSync(fullPath); + } + } + } catch { + // File may have been removed between readdir and stat — ignore + } + } + } catch { + // Non-critical — don't let cleanup failures break output + } +} + function output(result, raw, rawValue) { + let data; if (raw && rawValue !== undefined) { - process.stdout.write(String(rawValue)); + data = String(rawValue); } else { const json = JSON.stringify(result, null, 2); // Large payloads exceed OpenCode's bash tool buffer (~50KB). // write to tmpfile and output the path prefixed with @file: so callers can detect it. if (json.length > 50000) { + reapStaleTempFiles(); const tmpPath = path.join(require('os').tmpdir(), `gsd-${Date.now()}.json`); fs.writeFileSync(tmpPath, json, 'utf-8'); - process.stdout.write('@file:' + tmpPath); + data = '@file:' + tmpPath; } else { - process.stdout.write(json); + data = json; } } - process.exit(0); + // process.stdout.write() is async when stdout is a pipe — process.exit() + // can tear down the process before the reader consumes the buffer. + // fs.writeSync(1, ...) blocks until the kernel accepts the bytes, and + // skipping process.exit() lets the event loop drain naturally. + fs.writeSync(1, data); } function error(message) { - process.stderr.write('Error: ' + message + '\n'); + fs.writeSync(2, 'Error: ' + message + '\n'); process.exit(1); } @@ -74,12 +203,20 @@ function loadConfig(cwd) { branching_strategy: 'none', phase_branch_template: 'gsd/phase-{phase}-{slug}', milestone_branch_template: 'gsd/{milestone}-{slug}', + quick_branch_template: null, research: true, plan_checker: true, verifier: true, nyquist_validation: true, parallelization: true, brave_search: false, + firecrawl: false, + exa_search: false, + text_mode: false, // when true, use plain-text numbered lists instead of question menus + sub_repos: [], + resolve_model_ids: false, // false: return alias as-is | true: map to full OpenCode model ID | "omit": return '' (runtime uses its default) + context_window: 200000, // default 200k; set to 1000000 for Opus/Sonnet 4.6 1M models + phase_naming: 'sequential', // 'sequential' (default, auto-increment) or 'custom' (arbitrary string IDs) }; try { @@ -91,6 +228,39 @@ function loadConfig(cwd) { const depthToGranularity = { quick: 'coarse', standard: 'standard', comprehensive: 'fine' }; parsed.granularity = depthToGranularity[parsed.depth] || parsed.depth; delete parsed.depth; + try { fs.writeFileSync(configPath, JSON.stringify(parsed, null, 2), 'utf-8'); } catch { /* intentionally empty */ } + } + + // Auto-detect and sync sub_repos: scan for child directories with .git + let configDirty = false; + + // Migrate legacy "multiRepo: true" boolean → sub_repos array + if (parsed.multiRepo === true && !parsed.sub_repos && !parsed.planning?.sub_repos) { + const detected = detectSubRepos(cwd); + if (detected.length > 0) { + parsed.sub_repos = detected; + if (!parsed.planning) parsed.planning = {}; + parsed.planning.commit_docs = false; + delete parsed.multiRepo; + configDirty = true; + } + } + + // Keep sub_repos in sync with actual filesystem + const currentSubRepos = parsed.sub_repos || parsed.planning?.sub_repos || []; + if (Array.isArray(currentSubRepos) && currentSubRepos.length > 0) { + const detected = detectSubRepos(cwd); + if (detected.length > 0) { + const sorted = [...currentSubRepos].sort(); + if (JSON.stringify(sorted) !== JSON.stringify(detected)) { + parsed.sub_repos = detected; + configDirty = true; + } + } + } + + // Persist sub_repos changes (migration or sync) + if (configDirty) { try { fs.writeFileSync(configPath, JSON.stringify(parsed, null, 2), 'utf-8'); } catch {} } @@ -111,18 +281,35 @@ function loadConfig(cwd) { return { model_profile: get('model_profile') ?? defaults.model_profile, - commit_docs: get('commit_docs', { section: 'planning', field: 'commit_docs' }) ?? defaults.commit_docs, + commit_docs: (() => { + const explicit = get('commit_docs', { section: 'planning', field: 'commit_docs' }); + // If explicitly set in config, respect the user's choice + if (explicit !== undefined) return explicit; + // Auto-detection: when no explicit value and .planning/ is gitignored, + // default to false instead of true + if (isGitIgnored(cwd, '.planning/')) return false; + return defaults.commit_docs; + })(), search_gitignored: get('search_gitignored', { section: 'planning', field: 'search_gitignored' }) ?? defaults.search_gitignored, branching_strategy: get('branching_strategy', { section: 'git', field: 'branching_strategy' }) ?? defaults.branching_strategy, phase_branch_template: get('phase_branch_template', { section: 'git', field: 'phase_branch_template' }) ?? defaults.phase_branch_template, milestone_branch_template: get('milestone_branch_template', { section: 'git', field: 'milestone_branch_template' }) ?? defaults.milestone_branch_template, + quick_branch_template: get('quick_branch_template', { section: 'git', field: 'quick_branch_template' }) ?? defaults.quick_branch_template, research: get('research', { section: 'workflow', field: 'research' }) ?? defaults.research, plan_checker: get('plan_checker', { section: 'workflow', field: 'plan_check' }) ?? defaults.plan_checker, verifier: get('verifier', { section: 'workflow', field: 'verifier' }) ?? defaults.verifier, nyquist_validation: get('nyquist_validation', { section: 'workflow', field: 'nyquist_validation' }) ?? defaults.nyquist_validation, parallelization, brave_search: get('brave_search') ?? defaults.brave_search, + firecrawl: get('firecrawl') ?? defaults.firecrawl, + exa_search: get('exa_search') ?? defaults.exa_search, + text_mode: get('text_mode', { section: 'workflow', field: 'text_mode' }) ?? defaults.text_mode, + sub_repos: get('sub_repos', { section: 'planning', field: 'sub_repos' }) ?? defaults.sub_repos, + resolve_model_ids: get('resolve_model_ids') ?? defaults.resolve_model_ids, + context_window: get('context_window') ?? defaults.context_window, + phase_naming: get('phase_naming') ?? defaults.phase_naming, model_overrides: parsed.model_overrides || null, + agent_skills: parsed.agent_skills || {}, }; } catch { return defaults; @@ -137,7 +324,9 @@ function isGitIgnored(cwd, targetPath) { // Without it, git check-ignore returns "not ignored" for tracked files even when // .gitignore explicitly lists them — a common source of confusion when .planning/ // was committed before being added to .gitignore. - execSync('git check-ignore -q --no-index -- ' + targetPath.replace(/[^a-zA-Z0-9._\-/]/g, ''), { + // Use execFileSync (array args) to prevent shell interpretation of special characters + // in file paths — avoids command injection via crafted path names. + execFileSync('git', ['check-ignore', '-q', '--no-index', '--', targetPath], { cwd, stdio: 'pipe', }); @@ -147,27 +336,281 @@ function isGitIgnored(cwd, targetPath) { } } +// ─── Markdown normalization ───────────────────────────────────────────────── + +/** + * Normalize markdown to fix common markdownlint violations. + * Applied at write points so GSD-generated .planning/ files are IDE-friendly. + * + * Rules enforced: + * MD022 — Blank lines around headings + * MD031 — Blank lines around fenced code blocks + * MD032 — Blank lines around lists + * MD012 — No multiple consecutive blank lines (collapsed to 2 max) + * MD047 — Files end with a single newline + */ +function normalizeMd(content) { + if (!content || typeof content !== 'string') return content; + + // Normalize line endings to LF for consistent processing + let text = content.replace(/\r\n/g, '\n'); + + const lines = text.split('\n'); + const result = []; + + for (let i = 0; i < lines.length; i++) { + const line = lines[i]; + const prev = i > 0 ? lines[i - 1] : ''; + const prevTrimmed = prev.trimEnd(); + const trimmed = line.trimEnd(); + + // MD022: Blank line before headings (skip first line and frontmatter delimiters) + if (/^#{1,6}\s/.test(trimmed) && i > 0 && prevTrimmed !== '' && prevTrimmed !== '---') { + result.push(''); + } + + // MD031: Blank line before fenced code blocks + if (/^```/.test(trimmed) && i > 0 && prevTrimmed !== '' && !isInsideFencedBlock(lines, i)) { + result.push(''); + } + + // MD032: Blank line before lists (- item, * item, N. item, - [ ] item) + if (/^(\s*[-*+]\s|\s*\d+\.\s)/.test(line) && i > 0 && + prevTrimmed !== '' && !/^(\s*[-*+]\s|\s*\d+\.\s)/.test(prev) && + prevTrimmed !== '---') { + result.push(''); + } + + result.push(line); + + // MD022: Blank line after headings + if (/^#{1,6}\s/.test(trimmed) && i < lines.length - 1) { + const next = lines[i + 1]; + if (next !== undefined && next.trimEnd() !== '') { + result.push(''); + } + } + + // MD031: Blank line after closing fenced code blocks + if (/^```\s*$/.test(trimmed) && isClosingFence(lines, i) && i < lines.length - 1) { + const next = lines[i + 1]; + if (next !== undefined && next.trimEnd() !== '') { + result.push(''); + } + } + + // MD032: Blank line after last list item in a block + if (/^(\s*[-*+]\s|\s*\d+\.\s)/.test(line) && i < lines.length - 1) { + const next = lines[i + 1]; + if (next !== undefined && next.trimEnd() !== '' && + !/^(\s*[-*+]\s|\s*\d+\.\s)/.test(next) && + !/^\s/.test(next)) { + // Only add blank line if next line is not a continuation/indented line + result.push(''); + } + } + } + + text = result.join('\n'); + + // MD012: Collapse 3+ consecutive blank lines to 2 + text = text.replace(/\n{3,}/g, '\n\n'); + + // MD047: Ensure file ends with exactly one newline + text = text.replace(/\n*$/, '\n'); + + return text; +} + +/** Check if line index i is inside an already-open fenced code block */ +function isInsideFencedBlock(lines, i) { + let fenceCount = 0; + for (let j = 0; j < i; j++) { + if (/^```/.test(lines[j].trimEnd())) fenceCount++; + } + return fenceCount % 2 === 1; +} + +/** Check if a ``` line is a closing fence (odd number of fences up to and including this one) */ +function isClosingFence(lines, i) { + let fenceCount = 0; + for (let j = 0; j <= i; j++) { + if (/^```/.test(lines[j].trimEnd())) fenceCount++; + } + return fenceCount % 2 === 0; +} + function execGit(cwd, args) { + const result = spawnSync('git', args, { + cwd, + stdio: 'pipe', + encoding: 'utf-8', + }); + return { + exitCode: result.status ?? 1, + stdout: (result.stdout ?? '').toString().trim(), + stderr: (result.stderr ?? '').toString().trim(), + }; +} + +// ─── Common path helpers ────────────────────────────────────────────────────── + +/** + * Resolve the main worktree root when running inside a git worktree. + * In a linked worktree, .planning/ lives in the main worktree, not in the linked one. + * Returns the main worktree path, or cwd if not in a worktree. + */ +function resolveWorktreeRoot(cwd) { + // If the current directory already has its own .planning/, respect it. + // This handles linked worktrees with independent planning state (e.g., Conductor workspaces). + if (fs.existsSync(path.join(cwd, '.planning'))) { + return cwd; + } + + // Check if we're in a linked worktree + const gitDir = execGit(cwd, ['rev-parse', '--git-dir']); + const commonDir = execGit(cwd, ['rev-parse', '--git-common-dir']); + + if (gitDir.exitCode !== 0 || commonDir.exitCode !== 0) return cwd; + + // In a linked worktree, .git is a file pointing to .git/worktrees/ + // and git-common-dir points to the main repo's .git directory + const gitDirResolved = path.resolve(cwd, gitDir.stdout); + const commonDirResolved = path.resolve(cwd, commonDir.stdout); + + if (gitDirResolved !== commonDirResolved) { + // We're in a linked worktree — resolve main worktree root + // The common dir is the main repo's .git, so its parent is the main worktree root + return path.dirname(commonDirResolved); + } + + return cwd; +} + +/** + * Acquire a file-based lock for .planning/ writes. + * Prevents concurrent worktrees from corrupting shared planning files. + * Lock is auto-released after the callback completes. + */ +function withPlanningLock(cwd, fn) { + const lockPath = path.join(planningDir(cwd), '.lock'); + const lockTimeout = 10000; // 10 seconds + const retryDelay = 100; + const start = Date.now(); + + // Ensure .planning/ exists + try { fs.mkdirSync(planningDir(cwd), { recursive: true }); } catch { /* ok */ } + + while (Date.now() - start < lockTimeout) { + try { + // Atomic create — fails if file exists + fs.writeFileSync(lockPath, JSON.stringify({ + pid: process.pid, + cwd, + acquired: new Date().toISOString(), + }), { flag: 'wx' }); + + // Lock acquired — run the function + try { + return fn(); + } finally { + try { fs.unlinkSync(lockPath); } catch { /* already released */ } + } + } catch (err) { + if (err.code === 'EEXIST') { + // Lock exists — check if stale (>30s old) + try { + const stat = fs.statSync(lockPath); + if (Date.now() - stat.mtimeMs > 30000) { + fs.unlinkSync(lockPath); + continue; // retry + } + } catch { continue; } + + // Wait and retry + spawnSync('sleep', ['0.1'], { stdio: 'ignore' }); + continue; + } + throw err; + } + } + // Timeout — force acquire (stale lock recovery) + try { fs.unlinkSync(lockPath); } catch { /* ok */ } + return fn(); +} + +/** + * Get the .planning directory path, workstream-aware. + * When a workstream is active (via explicit ws arg or GSD_WORKSTREAM env var), + * returns `.planning/workstreams/{ws}/`. Otherwise returns `.planning/`. + * + * @param {string} cwd - project root + * @param {string} [ws] - explicit workstream name; if omitted, checks GSD_WORKSTREAM env var + */ +function planningDir(cwd, ws) { + if (ws === undefined) ws = process.env.GSD_WORKSTREAM || null; + if (!ws) return path.join(cwd, '.planning'); + return path.join(cwd, '.planning', 'workstreams', ws); +} + +/** Always returns the root .planning/ path, ignoring workstreams. For shared resources. */ +function planningRoot(cwd) { + return path.join(cwd, '.planning'); +} + +/** + * Get common .planning file paths, workstream-aware. + * Scoped paths (state, roadmap, phases, requirements) resolve to the active workstream. + * Shared paths (project, config) always resolve to the root .planning/. + */ +function planningPaths(cwd, ws) { + const base = planningDir(cwd, ws); + const root = path.join(cwd, '.planning'); + return { + planning: base, + state: path.join(base, 'STATE.md'), + roadmap: path.join(base, 'ROADMAP.md'), + project: path.join(root, 'PROJECT.md'), + config: path.join(root, 'config.json'), + phases: path.join(base, 'phases'), + requirements: path.join(base, 'REQUIREMENTS.md'), + }; +} + +// ─── Active Workstream Detection ───────────────────────────────────────────── + +/** + * Get the active workstream name from .planning/active-workstream file. + * Returns null if no active workstream or file doesn't exist. + */ +function getActiveWorkstream(cwd) { + const filePath = path.join(planningRoot(cwd), 'active-workstream'); try { - const escaped = args.map(a => { - if (/^[a-zA-Z0-9._\-/=:@]+$/.test(a)) return a; - return "'" + a.replace(/'/g, "'\\''") + "'"; - }); - const stdout = execSync('git ' + escaped.join(' '), { - cwd, - stdio: 'pipe', - encoding: 'utf-8', - }); - return { exitCode: 0, stdout: stdout.trim(), stderr: '' }; - } catch (err) { - return { - exitCode: err.status ?? 1, - stdout: (err.stdout ?? '').toString().trim(), - stderr: (err.stderr ?? '').toString().trim(), - }; + const name = fs.readFileSync(filePath, 'utf-8').trim(); + if (!name || !/^[a-zA-Z0-9_-]+$/.test(name)) return null; + const wsDir = path.join(planningRoot(cwd), 'workstreams', name); + if (!fs.existsSync(wsDir)) return null; + return name; + } catch { + return null; } } +/** + * Set the active workstream. Pass null to clear. + */ +function setActiveWorkstream(cwd, name) { + const filePath = path.join(planningRoot(cwd), 'active-workstream'); + if (!name) { + try { fs.unlinkSync(filePath); } catch {} + return; + } + if (!/^[a-zA-Z0-9_-]+$/.test(name)) { + throw new Error('Invalid workstream name: must be alphanumeric, hyphens, and underscores only'); + } + fs.writeFileSync(filePath, name + '\n', 'utf-8'); +} + // ─── Phase utilities ────────────────────────────────────────────────────────── function escapeRegex(value) { @@ -175,17 +618,23 @@ function escapeRegex(value) { } function normalizePhaseName(phase) { - const match = String(phase).match(/^(\d+)([A-Z])?((?:\.\d+)*)/i); - if (!match) return phase; - const padded = match[1].padStart(2, '0'); - const letter = match[2] ? match[2].toUpperCase() : ''; - const decimal = match[3] || ''; - return padded + letter + decimal; + const str = String(phase); + // Standard numeric phases: 1, 01, 12A, 12.1 + const match = str.match(/^(\d+)([A-Z])?((?:\.\d+)*)/i); + if (match) { + const padded = match[1].padStart(2, '0'); + const letter = match[2] ? match[2].toUpperCase() : ''; + const decimal = match[3] || ''; + return padded + letter + decimal; + } + // Custom phase IDs (e.g. PROJ-42, AUTH-101): return as-is + return str; } function comparePhaseNum(a, b) { const pa = String(a).match(/^(\d+)([A-Z])?((?:\.\d+)*)/i); const pb = String(b).match(/^(\d+)([A-Z])?((?:\.\d+)*)/i); + // If either is non-numeric (custom ID), fall back to string comparison if (!pa || !pb) return String(a).localeCompare(String(b)); const intDiff = parseInt(pa[1], 10) - parseInt(pb[1], 10); if (intDiff !== 0) return intDiff; @@ -213,22 +662,26 @@ function comparePhaseNum(a, b) { function searchPhaseInDir(baseDir, relBase, normalized) { try { - const entries = fs.readdirSync(baseDir, { withFileTypes: true }); - const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort((a, b) => comparePhaseNum(a, b)); - const match = dirs.find(d => d.startsWith(normalized)); + const dirs = readSubdirectories(baseDir, true); + // Match: starts with normalized (numeric) OR contains normalized as prefix segment (custom ID) + const match = dirs.find(d => { + if (d.startsWith(normalized)) return true; + // For custom IDs like PROJ-42, match case-insensitively + if (d.toUpperCase().startsWith(normalized.toUpperCase())) return true; + return false; + }); if (!match) return null; - const dirMatch = match.match(/^(\d+[A-Z]?(?:\.\d+)*)-?(.*)/i); + // Extract phase number and name — supports both numeric (01-name) and custom (PROJ-42-name) + const dirMatch = match.match(/^(\d+[A-Z]?(?:\.\d+)*)-?(.*)/i) + || match.match(/^([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*)-(.+)/i) + || [null, match, null]; const phaseNumber = dirMatch ? dirMatch[1] : normalized; const phaseName = dirMatch && dirMatch[2] ? dirMatch[2] : null; const phaseDir = path.join(baseDir, match); - const phaseFiles = fs.readdirSync(phaseDir); - - const plans = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md').sort(); - const summaries = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md').sort(); - const hasResearch = phaseFiles.some(f => f.endsWith('-RESEARCH.md') || f === 'RESEARCH.md'); - const hasContext = phaseFiles.some(f => f.endsWith('-CONTEXT.md') || f === 'CONTEXT.md'); - const hasVerification = phaseFiles.some(f => f.endsWith('-VERIFICATION.md') || f === 'VERIFICATION.md'); + const { plans: unsortedPlans, summaries: unsortedSummaries, hasResearch, hasContext, hasVerification, hasReviews } = getPhaseFileStats(phaseDir); + const plans = unsortedPlans.sort(); + const summaries = unsortedSummaries.sort(); const completedPlanIds = new Set( summaries.map(s => s.replace('-SUMMARY.md', '').replace('SUMMARY.md', '')) @@ -250,6 +703,7 @@ function searchPhaseInDir(baseDir, relBase, normalized) { has_research: hasResearch, has_context: hasContext, has_verification: hasVerification, + has_reviews: hasReviews, }; } catch { return null; @@ -259,11 +713,12 @@ function searchPhaseInDir(baseDir, relBase, normalized) { function findPhaseInternal(cwd, phase) { if (!phase) return null; - const phasesDir = path.join(cwd, '.planning', 'phases'); + const phasesDir = path.join(planningDir(cwd), 'phases'); const normalized = normalizePhaseName(phase); // Search current phases first - const current = searchPhaseInDir(phasesDir, '.planning/phases', normalized); + const relPhasesDir = toPosixPath(path.relative(cwd, phasesDir)); + const current = searchPhaseInDir(phasesDir, relPhasesDir, normalized); if (current) return current; // Search archived milestone phases (newest first) @@ -288,7 +743,7 @@ function findPhaseInternal(cwd, phase) { return result; } } - } catch {} + } catch { /* intentionally empty */ } return null; } @@ -311,8 +766,7 @@ function getArchivedPhaseDirs(cwd) { for (const archiveName of phaseDirs) { const version = archiveName.match(/^(v[\d.]+)-phases$/)[1]; const archivePath = path.join(milestonesDir, archiveName); - const entries = fs.readdirSync(archivePath, { withFileTypes: true }); - const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort((a, b) => comparePhaseNum(a, b)); + const dirs = readSubdirectories(archivePath, true); for (const dir of dirs) { results.push({ @@ -323,21 +777,135 @@ function getArchivedPhaseDirs(cwd) { }); } } - } catch {} + } catch { /* intentionally empty */ } return results; } +// ─── Roadmap milestone scoping ─────────────────────────────────────────────── + +/** + * Strip shipped milestone content wrapped in
blocks. + * Used to isolate current milestone phases when searching ROADMAP.md + * for phase headings or checkboxes — prevents matching archived milestone + * phases that share the same numbers as current milestone phases. + */ +function stripShippedMilestones(content) { + return content.replace(/
[\s\S]*?<\/details>/gi, ''); +} + +/** + * Extract the current milestone section from ROADMAP.md by positive lookup. + * + * Instead of stripping
blocks (negative heuristic that breaks if + * agents wrap the current milestone in
), this finds the section + * matching the current milestone version and returns only that content. + * + * Falls back to stripShippedMilestones() if: + * - cwd is not provided + * - STATE.md doesn't exist or has no milestone field + * - Version can't be found in ROADMAP.md + * + * @param {string} content - Full ROADMAP.md content + * @param {string} [cwd] - Working directory for reading STATE.md + * @returns {string} Content scoped to current milestone + */ +function extractCurrentMilestone(content, cwd) { + if (!cwd) return stripShippedMilestones(content); + + // 1. Get current milestone version from STATE.md frontmatter + let version = null; + try { + const statePath = path.join(planningDir(cwd), 'STATE.md'); + if (fs.existsSync(statePath)) { + const stateRaw = fs.readFileSync(statePath, 'utf-8'); + const milestoneMatch = stateRaw.match(/^milestone:\s*(.+)/m); + if (milestoneMatch) { + version = milestoneMatch[1].trim(); + } + } + } catch {} + + // 2. Fallback: derive version from getMilestoneInfo pattern in ROADMAP.md itself + if (!version) { + // Check for 🚧 in-progress marker + const inProgressMatch = content.match(/🚧\s*\*\*v(\d+\.\d+)\s/); + if (inProgressMatch) { + version = 'v' + inProgressMatch[1]; + } + } + + if (!version) return stripShippedMilestones(content); + + // 3. Find the section matching this version + // Match headings like: ## Roadmap v3.0: Name, ## v3.0 Name, etc. + const escapedVersion = escapeRegex(version); + const sectionPattern = new RegExp( + `(^#{1,3}\\s+.*${escapedVersion}[^\\n]*)`, + 'mi' + ); + const sectionMatch = content.match(sectionPattern); + + if (!sectionMatch) return stripShippedMilestones(content); + + const sectionStart = sectionMatch.index; + + // Find the end: next milestone heading at same or higher level, or EOF + // Milestone headings look like: ## v2.0, ## Roadmap v2.0, ## ✅ v1.0, etc. + const headingLevel = sectionMatch[1].match(/^(#{1,3})\s/)[1].length; + const restContent = content.slice(sectionStart + sectionMatch[0].length); + const nextMilestonePattern = new RegExp( + `^#{1,${headingLevel}}\\s+(?:.*v\\d+\\.\\d+|✅|📋|🚧)`, + 'mi' + ); + const nextMatch = restContent.match(nextMilestonePattern); + + let sectionEnd; + if (nextMatch) { + sectionEnd = sectionStart + sectionMatch[0].length + nextMatch.index; + } else { + sectionEnd = content.length; + } + + // Return everything before the current milestone section (non-milestone content + // like title, overview) plus the current milestone section + const beforeMilestones = content.slice(0, sectionStart); + const currentSection = content.slice(sectionStart, sectionEnd); + + // Also include any content before the first milestone heading (title, overview, etc.) + // but strip any
blocks in it (these are definitely shipped) + const preamble = beforeMilestones.replace(/
[\s\S]*?<\/details>/gi, ''); + + return preamble + currentSection; +} + +/** + * Replace a pattern only in the current milestone section of ROADMAP.md + * (everything after the last
close tag). Used for write operations + * that must not accidentally modify archived milestone checkboxes/tables. + */ +function replaceInCurrentMilestone(content, pattern, replacement) { + const lastDetailsClose = content.lastIndexOf('
'); + if (lastDetailsClose === -1) { + return content.replace(pattern, replacement); + } + const offset = lastDetailsClose + '
'.length; + const before = content.slice(0, offset); + const after = content.slice(offset); + return before + after.replace(pattern, replacement); +} + // ─── Roadmap & model utilities ──────────────────────────────────────────────── function getRoadmapPhaseInternal(cwd, phaseNum) { if (!phaseNum) return null; - const roadmapPath = path.join(cwd, '.planning', 'ROADMAP.md'); + const roadmapPath = path.join(planningDir(cwd), 'ROADMAP.md'); if (!fs.existsSync(roadmapPath)) return null; try { - const content = fs.readFileSync(roadmapPath, 'utf-8'); + const content = extractCurrentMilestone(fs.readFileSync(roadmapPath, 'utf-8'), cwd); const escapedPhase = escapeRegex(phaseNum.toString()); + // Match both numeric (Phase 1:) and custom (Phase PROJ-42:) headers const phasePattern = new RegExp(`#{2,4}\\s*Phase\\s+${escapedPhase}:\\s*([^\\n]+)`, 'i'); const headerMatch = content.match(phasePattern); if (!headerMatch) return null; @@ -345,11 +913,11 @@ function getRoadmapPhaseInternal(cwd, phaseNum) { const phaseName = headerMatch[1].trim(); const headerIndex = headerMatch.index; const restOfContent = content.slice(headerIndex); - const nextHeaderMatch = restOfContent.match(/\n#{2,4}\s+Phase\s+\d/i); + const nextHeaderMatch = restOfContent.match(/\n#{2,4}\s+Phase\s+[\w]/i); const sectionEnd = nextHeaderMatch ? headerIndex + nextHeaderMatch.index : content.length; const section = content.slice(headerIndex, sectionEnd).trim(); - const goalMatch = section.match(/\*\*Goal:\*\*\s*([^\n]+)/i); + const goalMatch = section.match(/\*\*Goal(?:\*\*:|\*?\*?:\*\*)\s*([^\n]+)/i); const goal = goalMatch ? goalMatch[1].trim() : null; return { @@ -364,21 +932,119 @@ function getRoadmapPhaseInternal(cwd, phaseNum) { } } +// ─── Agent installation validation (#1371) ─────────────────────────────────── + +/** + * Resolve the agents directory from the GSD install location. + * gsd-tools.cjs lives at /get-shit-done/bin/gsd-tools.cjs, + * so agents/ is at /agents/. + * + * @returns {string} Absolute path to the agents directory + */ +function getAgentsDir() { + // __dirname is get-shit-done/bin/lib/ → go up 3 levels to configDir + return path.join(__dirname, '..', '..', '..', 'agents'); +} + +/** + * Check which GSD agents are installed on disk. + * Returns an object with installation status and details. + * + * @returns {{ agents_installed: boolean, missing_agents: string[], installed_agents: string[], agents_dir: string }} + */ +function checkAgentsInstalled() { + const agentsDir = getAgentsDir(); + const expectedAgents = Object.keys(MODEL_PROFILES); + const installed = []; + const missing = []; + + if (!fs.existsSync(agentsDir)) { + return { + agents_installed: false, + missing_agents: expectedAgents, + installed_agents: [], + agents_dir: agentsDir, + }; + } + + for (const agent of expectedAgents) { + const agentFile = path.join(agentsDir, `${agent}.md`); + if (fs.existsSync(agentFile)) { + installed.push(agent); + } else { + missing.push(agent); + } + } + + return { + agents_installed: installed.length > 0 && missing.length === 0, + missing_agents: missing, + installed_agents: installed, + agents_dir: agentsDir, + }; +} + +// ─── Model alias resolution ─────────────────────────────────────────────────── + +/** + * Map short model aliases to full model IDs. + * Updated each release to match current model versions. + * Users can override with model_overrides in config.json for custom/latest models. + */ +const MODEL_ALIAS_MAP = { + 'opus': 'OpenCode-opus-4-0', + 'sonnet': 'OpenCode-sonnet-4-5', + 'haiku': 'OpenCode-haiku-3-5', +}; + function resolveModelInternal(cwd, agentType) { const config = loadConfig(cwd); - // Check per-agent override first + // Check per-agent override first — always respected regardless of resolve_model_ids. + // Users who set fully-qualified model IDs (e.g., "openai/gpt-5.4") get exactly that. const override = config.model_overrides?.[agentType]; if (override) { - return override === 'opus' ? 'inherit' : override; + return override; + } + + // resolve_model_ids: "omit" — return empty string so the runtime uses its configured + // default model. For non-OpenCode runtimes (OpenCode, Codex, etc.) that don't recognize + // OpenCode aliases (opus/sonnet/haiku/inherit). Set automatically during install. See #1156. + if (config.resolve_model_ids === 'omit') { + return ''; } // Fall back to profile lookup - const profile = config.model_profile || 'balanced'; + const profile = String(config.model_profile || 'balanced').toLowerCase(); const agentModels = MODEL_PROFILES[agentType]; if (!agentModels) return 'sonnet'; - const resolved = agentModels[profile] || agentModels['balanced'] || 'sonnet'; - return resolved === 'opus' ? 'inherit' : resolved; + if (profile === 'inherit') return 'inherit'; + const alias = agentModels[profile] || agentModels['balanced'] || 'sonnet'; + + // resolve_model_ids: true — map alias to full OpenCode model ID + // Prevents 404s when the task tool passes aliases directly to the API + if (config.resolve_model_ids) { + return MODEL_ALIAS_MAP[alias] || alias; + } + + return alias; +} + +// ─── Summary body helpers ───────────────────────────────────────────────── + +/** + * Extract a one-liner from the summary body when it's not in frontmatter. + * The summary template defines one-liner as a bold markdown line after the heading: + * # Phase X: Name Summary + * **[substantive one-liner text]** + */ +function extractOneLinerFromBody(content) { + if (!content) return null; + // Strip frontmatter first + const body = content.replace(/^---\n[\s\S]*?\n---\n*/, ''); + // Find the first **...** line after a # heading + const match = body.match(/^#[^\n]*\n+\*\*([^*]+)\*\*/m); + return match ? match[1].trim() : null; } // ─── Misc utilities ─────────────────────────────────────────────────────────── @@ -400,11 +1066,12 @@ function generateSlugInternal(text) { function getMilestoneInfo(cwd) { try { - const roadmap = fs.readFileSync(path.join(cwd, '.planning', 'ROADMAP.md'), 'utf-8'); + const roadmap = fs.readFileSync(path.join(planningDir(cwd), 'ROADMAP.md'), 'utf-8'); // First: check for list-format roadmaps using 🚧 (in-progress) marker // e.g. "- 🚧 **v2.1 Belgium** — Phases 24-28 (in progress)" - const inProgressMatch = roadmap.match(/🚧\s*\*\*v(\d+\.\d+)\s+([^*]+)\*\*/); + // e.g. "- 🚧 **v1.2.1 Tech Debt** — Phases 1-8 (in progress)" + const inProgressMatch = roadmap.match(/🚧\s*\*\*v(\d+(?:\.\d+)+)\s+([^*]+)\*\*/); if (inProgressMatch) { return { version: 'v' + inProgressMatch[1], @@ -413,17 +1080,18 @@ function getMilestoneInfo(cwd) { } // Second: heading-format roadmaps — strip shipped milestones in
blocks - const cleaned = roadmap.replace(/
[\s\S]*?<\/details>/gi, ''); + const cleaned = stripShippedMilestones(roadmap); // Extract version and name from the same ## heading for consistency - const headingMatch = cleaned.match(/## .*v(\d+\.\d+)[:\s]+([^\n(]+)/); + // Supports 2+ segment versions: v1.2, v1.2.1, v2.0.1, etc. + const headingMatch = cleaned.match(/## .*v(\d+(?:\.\d+)+)[:\s]+([^\n(]+)/); if (headingMatch) { return { version: 'v' + headingMatch[1], name: headingMatch[2].trim(), }; } - // Fallback: try bare version match - const versionMatch = cleaned.match(/v(\d+\.\d+)/); + // Fallback: try bare version match (greedy — capture longest version string) + const versionMatch = cleaned.match(/v(\d+(?:\.\d+)+)/); return { version: versionMatch ? versionMatch[0] : 'v1.0', name: 'milestone', @@ -441,13 +1109,14 @@ function getMilestoneInfo(cwd) { function getMilestonePhaseFilter(cwd) { const milestonePhaseNums = new Set(); try { - const roadmap = fs.readFileSync(path.join(cwd, '.planning', 'ROADMAP.md'), 'utf-8'); - const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:/gi; + const roadmap = extractCurrentMilestone(fs.readFileSync(path.join(planningDir(cwd), 'ROADMAP.md'), 'utf-8'), cwd); + // Match both numeric phases (Phase 1:) and custom IDs (Phase PROJ-42:) + const phasePattern = /#{2,4}\s*Phase\s+([\w][\w.-]*)\s*:/gi; let m; while ((m = phasePattern.exec(roadmap)) !== null) { milestonePhaseNums.add(m[1]); } - } catch {} + } catch { /* intentionally empty */ } if (milestonePhaseNums.size === 0) { const passAll = () => true; @@ -460,22 +1129,70 @@ function getMilestonePhaseFilter(cwd) { ); function isDirInMilestone(dirName) { + // Try numeric match first const m = dirName.match(/^0*(\d+[A-Za-z]?(?:\.\d+)*)/); - if (!m) return false; - return normalized.has(m[1].toLowerCase()); + if (m && normalized.has(m[1].toLowerCase())) return true; + // Try custom ID match (e.g. PROJ-42-description → PROJ-42) + const customMatch = dirName.match(/^([A-Za-z][A-Za-z0-9]*(?:-[A-Za-z0-9]+)*)/); + if (customMatch && normalized.has(customMatch[1].toLowerCase())) return true; + return false; } isDirInMilestone.phaseCount = milestonePhaseNums.size; return isDirInMilestone; } +// ─── Phase file helpers ────────────────────────────────────────────────────── + +/** Filter a file list to just PLAN.md / *-PLAN.md entries. */ +function filterPlanFiles(files) { + return files.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md'); +} + +/** Filter a file list to just SUMMARY.md / *-SUMMARY.md entries. */ +function filterSummaryFiles(files) { + return files.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md'); +} + +/** + * read a phase directory and return counts/flags for common file types. + * Returns an object with plans[], summaries[], and boolean flags for + * research/context/verification files. + */ +function getPhaseFileStats(phaseDir) { + const files = fs.readdirSync(phaseDir); + return { + plans: filterPlanFiles(files), + summaries: filterSummaryFiles(files), + hasResearch: files.some(f => f.endsWith('-RESEARCH.md') || f === 'RESEARCH.md'), + hasContext: files.some(f => f.endsWith('-CONTEXT.md') || f === 'CONTEXT.md'), + hasVerification: files.some(f => f.endsWith('-VERIFICATION.md') || f === 'VERIFICATION.md'), + hasReviews: files.some(f => f.endsWith('-REVIEWS.md') || f === 'REVIEWS.md'), + }; +} + +/** + * read immediate child directories from a path. + * Returns [] if the path doesn't exist or can't be read. + * Pass sort=true to apply comparePhaseNum ordering. + */ +function readSubdirectories(dirPath, sort = false) { + try { + const entries = fs.readdirSync(dirPath, { withFileTypes: true }); + const dirs = entries.filter(e => e.isDirectory()).map(e => e.name); + return sort ? dirs.sort((a, b) => comparePhaseNum(a, b)) : dirs; + } catch { + return []; + } +} + module.exports = { - MODEL_PROFILES, output, error, safeReadFile, loadConfig, isGitIgnored, execGit, + normalizeMd, escapeRegex, normalizePhaseName, comparePhaseNum, @@ -488,5 +1205,26 @@ module.exports = { generateSlugInternal, getMilestoneInfo, getMilestonePhaseFilter, + stripShippedMilestones, + extractCurrentMilestone, + replaceInCurrentMilestone, toPosixPath, + extractOneLinerFromBody, + resolveWorktreeRoot, + withPlanningLock, + findProjectRoot, + detectSubRepos, + reapStaleTempFiles, + MODEL_ALIAS_MAP, + planningDir, + planningRoot, + planningPaths, + getActiveWorkstream, + setActiveWorkstream, + filterPlanFiles, + filterSummaryFiles, + getPhaseFileStats, + readSubdirectories, + getAgentsDir, + checkAgentsInstalled, }; diff --git a/gsd-opencode/get-shit-done/bin/lib/frontmatter.cjs b/gsd-opencode/get-shit-done/bin/lib/frontmatter.cjs index 93dccb5..28690b0 100644 --- a/gsd-opencode/get-shit-done/bin/lib/frontmatter.cjs +++ b/gsd-opencode/get-shit-done/bin/lib/frontmatter.cjs @@ -4,17 +4,21 @@ const fs = require('fs'); const path = require('path'); -const { safeReadFile, output, error } = require('./core.cjs'); +const { safeReadFile, normalizeMd, output, error } = require('./core.cjs'); // ─── Parsing engine ─────────────────────────────────────────────────────────── function extractFrontmatter(content) { const frontmatter = {}; - const match = content.match(/^---\n([\s\S]+?)\n---/); + // Find ALL frontmatter blocks at the start of the file. + // If multiple blocks exist (corruption from CRLF mismatch), use the LAST one + // since it represents the most recent state sync. + const allBlocks = [...content.matchAll(/(?:^|\n)\s*---\r?\n([\s\S]+?)\r?\n---/g)]; + const match = allBlocks.length > 0 ? allBlocks[allBlocks.length - 1] : null; if (!match) return frontmatter; const yaml = match[1]; - const lines = yaml.split('\n'); + const lines = yaml.split(/\r?\n/); // Stack to track nested objects: [{obj, key, indent}] // obj = object to write to, key = current key collecting array items, indent = indentation level @@ -149,7 +153,7 @@ function reconstructFrontmatter(obj) { function spliceFrontmatter(content, newObj) { const yamlStr = reconstructFrontmatter(newObj); - const match = content.match(/^---\n[\s\S]+?\n---/); + const match = content.match(/^---\r?\n[\s\S]+?\r?\n---/); if (match) { return `---\n${yamlStr}\n---` + content.slice(match[0].length); } @@ -159,61 +163,90 @@ function spliceFrontmatter(content, newObj) { function parseMustHavesBlock(content, blockName) { // Extract a specific block from must_haves in raw frontmatter YAML // Handles 3-level nesting: must_haves > artifacts/key_links > [{path, provides, ...}] - const fmMatch = content.match(/^---\n([\s\S]+?)\n---/); + const fmMatch = content.match(/^---\r?\n([\s\S]+?)\r?\n---/); if (!fmMatch) return []; const yaml = fmMatch[1]; - // Find the block (e.g., "truths:", "artifacts:", "key_links:") - const blockPattern = new RegExp(`^\\s{4}${blockName}:\\s*$`, 'm'); - const blockStart = yaml.search(blockPattern); + + // Find must_haves: first to detect its indentation level + const mustHavesMatch = yaml.match(/^(\s*)must_haves:\s*$/m); + if (!mustHavesMatch) return []; + const mustHavesIndent = mustHavesMatch[1].length; + + // Find the block (e.g., "truths:", "artifacts:", "key_links:") under must_haves + // It must be indented more than must_haves but we detect the actual indent dynamically + const blockPattern = new RegExp(`^(\\s+)${blockName}:\\s*$`, 'm'); + const blockMatch = yaml.match(blockPattern); + if (!blockMatch) return []; + + const blockIndent = blockMatch[1].length; + // The block must be nested under must_haves (more indented) + if (blockIndent <= mustHavesIndent) return []; + + // Find where the block starts in the yaml string + const blockStart = yaml.indexOf(blockMatch[0]); if (blockStart === -1) return []; const afterBlock = yaml.slice(blockStart); - const blockLines = afterBlock.split('\n').slice(1); // skip the header line + const blockLines = afterBlock.split(/\r?\n/).slice(1); // skip the header line + // List items are indented one level deeper than blockIndent + // Continuation KVs are indented one level deeper than list items const items = []; let current = null; + let listItemIndent = -1; // detected from first "- " line for (const line of blockLines) { - // Stop at same or lower indent level (non-continuation) + // Skip empty lines if (line.trim() === '') continue; const indent = line.match(/^(\s*)/)[1].length; - if (indent <= 4 && line.trim() !== '') break; // back to must_haves level or higher - - if (line.match(/^\s{6}-\s+/)) { - // New list item at 6-space indent - if (current) items.push(current); - current = {}; - // Check if it's a simple string item - const simpleMatch = line.match(/^\s{6}-\s+"?([^"]+)"?\s*$/); - if (simpleMatch && !line.includes(':')) { - current = simpleMatch[1]; - } else { - // Key-value on same line as dash: "- path: value" - const kvMatch = line.match(/^\s{6}-\s+(\w+):\s*"?([^"]*)"?\s*$/); - if (kvMatch) { - current = {}; - current[kvMatch[1]] = kvMatch[2]; + // Stop at same or lower indent level than the block header + if (indent <= blockIndent && line.trim() !== '') break; + + const trimmed = line.trim(); + + if (trimmed.startsWith('- ')) { + // Detect list item indent from the first occurrence + if (listItemIndent === -1) listItemIndent = indent; + + // Only treat as a top-level list item if at the expected indent + if (indent === listItemIndent) { + if (current) items.push(current); + current = {}; + const afterDash = trimmed.slice(2); + // Check if it's a simple string item (no colon means not a key-value) + if (!afterDash.includes(':')) { + current = afterDash.replace(/^["']|["']$/g, ''); + } else { + // Key-value on same line as dash: "- path: value" + const kvMatch = afterDash.match(/^(\w+):\s*"?([^"]*)"?\s*$/); + if (kvMatch) { + current = {}; + current[kvMatch[1]] = kvMatch[2]; + } } + continue; } - } else if (current && typeof current === 'object') { - // Continuation key-value at 8+ space indent - const kvMatch = line.match(/^\s{8,}(\w+):\s*"?([^"]*)"?\s*$/); - if (kvMatch) { - const val = kvMatch[2]; - // Try to parse as number - current[kvMatch[1]] = /^\d+$/.test(val) ? parseInt(val, 10) : val; - } - // Array items under a key - const arrMatch = line.match(/^\s{10,}-\s+"?([^"]+)"?\s*$/); - if (arrMatch) { - // Find the last key added and convert to array + } + + if (current && typeof current === 'object' && indent > listItemIndent) { + // Continuation key-value or nested array item + if (trimmed.startsWith('- ')) { + // Array item under a key + const arrVal = trimmed.slice(2).replace(/^["']|["']$/g, ''); const keys = Object.keys(current); const lastKey = keys[keys.length - 1]; if (lastKey && !Array.isArray(current[lastKey])) { current[lastKey] = current[lastKey] ? [current[lastKey]] : []; } - if (lastKey) current[lastKey].push(arrMatch[1]); + if (lastKey) current[lastKey].push(arrVal); + } else { + const kvMatch = trimmed.match(/^(\w+):\s*"?([^"]*)"?\s*$/); + if (kvMatch) { + const val = kvMatch[2]; + // Try to parse as number + current[kvMatch[1]] = /^\d+$/.test(val) ? parseInt(val, 10) : val; + } } } } @@ -232,6 +265,8 @@ const FRONTMATTER_SCHEMAS = { function cmdFrontmatterGet(cwd, filePath, field, raw) { if (!filePath) { error('file path required'); } + // Path traversal guard: reject null bytes + if (filePath.includes('\0')) { error('file path contains null bytes'); } const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath); const content = safeReadFile(fullPath); if (!content) { output({ error: 'File not found', path: filePath }, raw); return; } @@ -247,6 +282,8 @@ function cmdFrontmatterGet(cwd, filePath, field, raw) { function cmdFrontmatterSet(cwd, filePath, field, value, raw) { if (!filePath || !field || value === undefined) { error('file, field, and value required'); } + // Path traversal guard: reject null bytes + if (filePath.includes('\0')) { error('file path contains null bytes'); } const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath); if (!fs.existsSync(fullPath)) { output({ error: 'File not found', path: filePath }, raw); return; } const content = fs.readFileSync(fullPath, 'utf-8'); @@ -255,7 +292,7 @@ function cmdFrontmatterSet(cwd, filePath, field, value, raw) { try { parsedValue = JSON.parse(value); } catch { parsedValue = value; } fm[field] = parsedValue; const newContent = spliceFrontmatter(content, fm); - fs.writeFileSync(fullPath, newContent, 'utf-8'); + fs.writeFileSync(fullPath, normalizeMd(newContent), 'utf-8'); output({ updated: true, field, value: parsedValue }, raw, 'true'); } @@ -269,7 +306,7 @@ function cmdFrontmatterMerge(cwd, filePath, data, raw) { try { mergeData = JSON.parse(data); } catch { error('Invalid JSON for --data'); return; } Object.assign(fm, mergeData); const newContent = spliceFrontmatter(content, fm); - fs.writeFileSync(fullPath, newContent, 'utf-8'); + fs.writeFileSync(fullPath, normalizeMd(newContent), 'utf-8'); output({ merged: true, fields: Object.keys(mergeData) }, raw, 'true'); } diff --git a/gsd-opencode/get-shit-done/bin/lib/init.cjs b/gsd-opencode/get-shit-done/bin/lib/init.cjs index 7e551a0..5f4e664 100644 --- a/gsd-opencode/get-shit-done/bin/lib/init.cjs +++ b/gsd-opencode/get-shit-done/bin/lib/init.cjs @@ -5,7 +5,40 @@ const fs = require('fs'); const path = require('path'); const { execSync } = require('child_process'); -const { loadConfig, resolveModelInternal, findPhaseInternal, getRoadmapPhaseInternal, pathExistsInternal, generateSlugInternal, getMilestoneInfo, normalizePhaseName, toPosixPath, output, error } = require('./core.cjs'); +const { loadConfig, resolveModelInternal, findPhaseInternal, getRoadmapPhaseInternal, pathExistsInternal, generateSlugInternal, getMilestoneInfo, getMilestonePhaseFilter, stripShippedMilestones, extractCurrentMilestone, normalizePhaseName, planningPaths, planningDir, planningRoot, toPosixPath, output, error, checkAgentsInstalled } = require('./core.cjs'); + +function getLatestCompletedMilestone(cwd) { + const milestonesPath = path.join(planningRoot(cwd), 'MILESTONES.md'); + if (!fs.existsSync(milestonesPath)) return null; + + try { + const content = fs.readFileSync(milestonesPath, 'utf-8'); + const match = content.match(/^##\s+(v[\d.]+)\s+(.+?)\s+\(Shipped:/m); + if (!match) return null; + return { + version: match[1], + name: match[2].trim(), + }; + } catch { + return null; + } +} + +/** + * Inject `project_root` into an init result object. + * Workflows use this to prefix `.planning/` paths correctly when OpenCode's CWD + * differs from the project root (e.g., inside a sub-repo). + */ +function withProjectRoot(cwd, result) { + result.project_root = cwd; + // Inject agent installation status into all init outputs (#1371). + // Workflows that spawn named subagents use this to detect when agents + // are missing and would silently fall back to general-purpose. + const agentStatus = checkAgentsInstalled(); + result.agents_installed = agentStatus.agents_installed; + result.missing_agents = agentStatus.missing_agents; + return result; +} function cmdInitExecutePhase(cwd, phase, raw) { if (!phase) { @@ -13,10 +46,29 @@ function cmdInitExecutePhase(cwd, phase, raw) { } const config = loadConfig(cwd); - const phaseInfo = findPhaseInternal(cwd, phase); + let phaseInfo = findPhaseInternal(cwd, phase); const milestone = getMilestoneInfo(cwd); const roadmapPhase = getRoadmapPhaseInternal(cwd, phase); + + // Fallback to ROADMAP.md if no phase directory exists yet + if (!phaseInfo && roadmapPhase?.found) { + const phaseName = roadmapPhase.phase_name; + phaseInfo = { + found: true, + directory: null, + phase_number: roadmapPhase.phase_number, + phase_name: phaseName, + phase_slug: phaseName ? phaseName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') : null, + plans: [], + summaries: [], + incomplete_plans: [], + has_research: false, + has_context: false, + has_verification: false, + has_reviews: false, + }; + } const reqMatch = roadmapPhase?.section?.match(/^\*\*Requirements\*\*:[^\S\n]*([^\n]*)$/m); const reqExtracted = reqMatch ? reqMatch[1].replace(/[\[\]]/g, '').split(',').map(s => s.trim()).filter(Boolean).join(', ') @@ -30,7 +82,9 @@ function cmdInitExecutePhase(cwd, phase, raw) { // Config flags commit_docs: config.commit_docs, + sub_repos: config.sub_repos, parallelization: config.parallelization, + context_window: config.context_window, branching_strategy: config.branching_strategy, phase_branch_template: config.phase_branch_template, milestone_branch_template: config.milestone_branch_template, @@ -68,16 +122,16 @@ function cmdInitExecutePhase(cwd, phase, raw) { milestone_slug: generateSlugInternal(milestone.name), // File existence - state_exists: pathExistsInternal(cwd, '.planning/STATE.md'), - roadmap_exists: pathExistsInternal(cwd, '.planning/ROADMAP.md'), - config_exists: pathExistsInternal(cwd, '.planning/config.json'), + state_exists: fs.existsSync(path.join(planningDir(cwd), 'STATE.md')), + roadmap_exists: fs.existsSync(path.join(planningDir(cwd), 'ROADMAP.md')), + config_exists: fs.existsSync(path.join(planningDir(cwd), 'config.json')), // File paths - state_path: '.planning/STATE.md', - roadmap_path: '.planning/ROADMAP.md', - config_path: '.planning/config.json', + state_path: toPosixPath(path.relative(cwd, path.join(planningDir(cwd), 'STATE.md'))), + roadmap_path: toPosixPath(path.relative(cwd, path.join(planningDir(cwd), 'ROADMAP.md'))), + config_path: toPosixPath(path.relative(cwd, path.join(planningDir(cwd), 'config.json'))), }; - output(result, raw); + output(withProjectRoot(cwd, result), raw); } function cmdInitPlanPhase(cwd, phase, raw) { @@ -86,9 +140,28 @@ function cmdInitPlanPhase(cwd, phase, raw) { } const config = loadConfig(cwd); - const phaseInfo = findPhaseInternal(cwd, phase); + let phaseInfo = findPhaseInternal(cwd, phase); const roadmapPhase = getRoadmapPhaseInternal(cwd, phase); + + // Fallback to ROADMAP.md if no phase directory exists yet + if (!phaseInfo && roadmapPhase?.found) { + const phaseName = roadmapPhase.phase_name; + phaseInfo = { + found: true, + directory: null, + phase_number: roadmapPhase.phase_number, + phase_name: phaseName, + phase_slug: phaseName ? phaseName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') : null, + plans: [], + summaries: [], + incomplete_plans: [], + has_research: false, + has_context: false, + has_verification: false, + has_reviews: false, + }; + } const reqMatch = roadmapPhase?.section?.match(/^\*\*Requirements\*\*:[^\S\n]*([^\n]*)$/m); const reqExtracted = reqMatch ? reqMatch[1].replace(/[\[\]]/g, '').split(',').map(s => s.trim()).filter(Boolean).join(', ') @@ -106,6 +179,7 @@ function cmdInitPlanPhase(cwd, phase, raw) { plan_checker_enabled: config.plan_checker, nyquist_validation_enabled: config.nyquist_validation, commit_docs: config.commit_docs, + text_mode: config.text_mode, // Phase info phase_found: !!phaseInfo, @@ -113,23 +187,24 @@ function cmdInitPlanPhase(cwd, phase, raw) { phase_number: phaseInfo?.phase_number || null, phase_name: phaseInfo?.phase_name || null, phase_slug: phaseInfo?.phase_slug || null, - padded_phase: phaseInfo?.phase_number?.padStart(2, '0') || null, + padded_phase: phaseInfo?.phase_number ? normalizePhaseName(phaseInfo.phase_number) : null, phase_req_ids, // Existing artifacts has_research: phaseInfo?.has_research || false, has_context: phaseInfo?.has_context || false, + has_reviews: phaseInfo?.has_reviews || false, has_plans: (phaseInfo?.plans?.length || 0) > 0, plan_count: phaseInfo?.plans?.length || 0, // Environment - planning_exists: pathExistsInternal(cwd, '.planning'), - roadmap_exists: pathExistsInternal(cwd, '.planning/ROADMAP.md'), + planning_exists: fs.existsSync(planningDir(cwd)), + roadmap_exists: fs.existsSync(path.join(planningDir(cwd), 'ROADMAP.md')), // File paths - state_path: '.planning/STATE.md', - roadmap_path: '.planning/ROADMAP.md', - requirements_path: '.planning/REQUIREMENTS.md', + state_path: toPosixPath(path.relative(cwd, path.join(planningDir(cwd), 'STATE.md'))), + roadmap_path: toPosixPath(path.relative(cwd, path.join(planningDir(cwd), 'ROADMAP.md'))), + requirements_path: toPosixPath(path.relative(cwd, path.join(planningDir(cwd), 'REQUIREMENTS.md'))), }; if (phaseInfo?.directory) { @@ -153,10 +228,14 @@ function cmdInitPlanPhase(cwd, phase, raw) { if (uatFile) { result.uat_path = toPosixPath(path.join(phaseInfo.directory, uatFile)); } - } catch {} + const reviewsFile = files.find(f => f.endsWith('-REVIEWS.md') || f === 'REVIEWS.md'); + if (reviewsFile) { + result.reviews_path = toPosixPath(path.join(phaseInfo.directory, reviewsFile)); + } + } catch { /* intentionally empty */ } } - output(result, raw); + output(withProjectRoot(cwd, result), raw); } function cmdInitNewProject(cwd, raw) { @@ -167,23 +246,67 @@ function cmdInitNewProject(cwd, raw) { const braveKeyFile = path.join(homedir, '.gsd', 'brave_api_key'); const hasBraveSearch = !!(process.env.BRAVE_API_KEY || fs.existsSync(braveKeyFile)); - // Detect existing code + // Detect Firecrawl API key availability + const firecrawlKeyFile = path.join(homedir, '.gsd', 'firecrawl_api_key'); + const hasFirecrawl = !!(process.env.FIRECRAWL_API_KEY || fs.existsSync(firecrawlKeyFile)); + + // Detect Exa API key availability + const exaKeyFile = path.join(homedir, '.gsd', 'exa_api_key'); + const hasExaSearch = !!(process.env.EXA_API_KEY || fs.existsSync(exaKeyFile)); + + // Detect existing code (cross-platform — no Unix `find` dependency) let hasCode = false; let hasPackageFile = false; try { - const files = execSync('find . -maxdepth 3 \\( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.swift" -o -name "*.java" \\) 2>/dev/null | grep -v node_modules | grep -v .git | head -5', { - cwd, - encoding: 'utf-8', - stdio: ['pipe', 'pipe', 'pipe'], - }); - hasCode = files.trim().length > 0; - } catch {} + const codeExtensions = new Set([ + '.ts', '.js', '.py', '.go', '.rs', '.swift', '.java', + '.kt', '.kts', // Kotlin (Android, server-side) + '.c', '.cpp', '.h', // C/C++ + '.cs', // C# + '.rb', // Ruby + '.php', // PHP + '.dart', // Dart (Flutter) + '.m', '.mm', // Objective-C / Objective-C++ + '.scala', // Scala + '.groovy', // Groovy (Gradle build scripts) + '.lua', // Lua + '.r', '.R', // R + '.zig', // Zig + '.ex', '.exs', // Elixir + '.clj', // Clojure + ]); + const skipDirs = new Set(['node_modules', '.git', '.planning', '.OpenCode', '__pycache__', 'target', 'dist', 'build']); + function findCodeFiles(dir, depth) { + if (depth > 3) return false; + let entries; + try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return false; } + for (const entry of entries) { + if (entry.isFile() && codeExtensions.has(path.extname(entry.name))) return true; + if (entry.isDirectory() && !skipDirs.has(entry.name)) { + if (findCodeFiles(path.join(dir, entry.name), depth + 1)) return true; + } + } + return false; + } + hasCode = findCodeFiles(cwd, 0); + } catch { /* intentionally empty — best-effort detection */ } hasPackageFile = pathExistsInternal(cwd, 'package.json') || pathExistsInternal(cwd, 'requirements.txt') || pathExistsInternal(cwd, 'Cargo.toml') || pathExistsInternal(cwd, 'go.mod') || - pathExistsInternal(cwd, 'Package.swift'); + pathExistsInternal(cwd, 'Package.swift') || + pathExistsInternal(cwd, 'build.gradle') || + pathExistsInternal(cwd, 'build.gradle.kts') || + pathExistsInternal(cwd, 'pom.xml') || + pathExistsInternal(cwd, 'Gemfile') || + pathExistsInternal(cwd, 'composer.json') || + pathExistsInternal(cwd, 'pubspec.yaml') || + pathExistsInternal(cwd, 'CMakeLists.txt') || + pathExistsInternal(cwd, 'Makefile') || + pathExistsInternal(cwd, 'build.zig') || + pathExistsInternal(cwd, 'mix.exs') || + pathExistsInternal(cwd, 'project.clj'); const result = { // Models @@ -210,17 +333,30 @@ function cmdInitNewProject(cwd, raw) { // Enhanced search brave_search_available: hasBraveSearch, + firecrawl_available: hasFirecrawl, + exa_search_available: hasExaSearch, // File paths project_path: '.planning/PROJECT.md', }; - output(result, raw); + output(withProjectRoot(cwd, result), raw); } function cmdInitNewMilestone(cwd, raw) { const config = loadConfig(cwd); const milestone = getMilestoneInfo(cwd); + const latestCompleted = getLatestCompletedMilestone(cwd); + const phasesDir = path.join(planningDir(cwd), 'phases'); + let phaseDirCount = 0; + + try { + if (fs.existsSync(phasesDir)) { + phaseDirCount = fs.readdirSync(phasesDir, { withFileTypes: true }) + .filter(entry => entry.isDirectory()) + .length; + } + } catch {} const result = { // Models @@ -235,19 +371,23 @@ function cmdInitNewMilestone(cwd, raw) { // Current milestone current_milestone: milestone.version, current_milestone_name: milestone.name, + latest_completed_milestone: latestCompleted?.version || null, + latest_completed_milestone_name: latestCompleted?.name || null, + phase_dir_count: phaseDirCount, + phase_archive_path: latestCompleted ? toPosixPath(path.relative(cwd, path.join(planningRoot(cwd), 'milestones', `${latestCompleted.version}-phases`))) : null, // File existence project_exists: pathExistsInternal(cwd, '.planning/PROJECT.md'), - roadmap_exists: pathExistsInternal(cwd, '.planning/ROADMAP.md'), - state_exists: pathExistsInternal(cwd, '.planning/STATE.md'), + roadmap_exists: fs.existsSync(path.join(planningDir(cwd), 'ROADMAP.md')), + state_exists: fs.existsSync(path.join(planningDir(cwd), 'STATE.md')), // File paths project_path: '.planning/PROJECT.md', - roadmap_path: '.planning/ROADMAP.md', - state_path: '.planning/STATE.md', + roadmap_path: toPosixPath(path.relative(cwd, path.join(planningDir(cwd), 'ROADMAP.md'))), + state_path: toPosixPath(path.relative(cwd, path.join(planningDir(cwd), 'STATE.md'))), }; - output(result, raw); + output(withProjectRoot(cwd, result), raw); } function cmdInitQuick(cwd, description, raw) { @@ -255,18 +395,25 @@ function cmdInitQuick(cwd, description, raw) { const now = new Date(); const slug = description ? generateSlugInternal(description)?.substring(0, 40) : null; - // Find next quick task number - const quickDir = path.join(cwd, '.planning', 'quick'); - let nextNum = 1; - try { - const existing = fs.readdirSync(quickDir) - .filter(f => /^\d+-/.test(f)) - .map(f => parseInt(f.split('-')[0], 10)) - .filter(n => !isNaN(n)); - if (existing.length > 0) { - nextNum = Math.max(...existing) + 1; - } - } catch {} + // Generate collision-resistant quick task ID: YYMMDD-xxx + // xxx = 2-second precision blocks since midnight, encoded as 3-char Base36 (lowercase) + // Range: 000 (00:00:00) to xbz (23:59:58), guaranteed 3 chars for any time of day. + // Provides ~2s uniqueness window per user — practically collision-free across a team. + const yy = String(now.getFullYear()).slice(-2); + const mm = String(now.getMonth() + 1).padStart(2, '0'); + const dd = String(now.getDate()).padStart(2, '0'); + const dateStr = yy + mm + dd; + const secondsSinceMidnight = now.getHours() * 3600 + now.getMinutes() * 60 + now.getSeconds(); + const timeBlocks = Math.floor(secondsSinceMidnight / 2); + const timeEncoded = timeBlocks.toString(36).padStart(3, '0'); + const quickId = dateStr + '-' + timeEncoded; + const branchSlug = slug || 'quick'; + const quickBranchName = config.quick_branch_template + ? config.quick_branch_template + .replace('{num}', quickId) + .replace('{quick}', quickId) + .replace('{slug}', branchSlug) + : null; const result = { // Models @@ -277,9 +424,10 @@ function cmdInitQuick(cwd, description, raw) { // Config commit_docs: config.commit_docs, + branch_name: quickBranchName, // Quick task info - next_num: nextNum, + quick_id: quickId, slug: slug, description: description || null, @@ -289,15 +437,15 @@ function cmdInitQuick(cwd, description, raw) { // Paths quick_dir: '.planning/quick', - task_dir: slug ? `.planning/quick/${nextNum}-${slug}` : null, + task_dir: slug ? `.planning/quick/${quickId}-${slug}` : null, // File existence - roadmap_exists: pathExistsInternal(cwd, '.planning/ROADMAP.md'), - planning_exists: pathExistsInternal(cwd, '.planning'), + roadmap_exists: fs.existsSync(path.join(planningDir(cwd), 'ROADMAP.md')), + planning_exists: fs.existsSync(planningRoot(cwd)), }; - output(result, raw); + output(withProjectRoot(cwd, result), raw); } function cmdInitResume(cwd, raw) { @@ -306,19 +454,19 @@ function cmdInitResume(cwd, raw) { // Check for interrupted agent let interruptedAgentId = null; try { - interruptedAgentId = fs.readFileSync(path.join(cwd, '.planning', 'current-agent-id.txt'), 'utf-8').trim(); - } catch {} + interruptedAgentId = fs.readFileSync(path.join(planningRoot(cwd), 'current-agent-id.txt'), 'utf-8').trim(); + } catch { /* intentionally empty */ } const result = { // File existence - state_exists: pathExistsInternal(cwd, '.planning/STATE.md'), - roadmap_exists: pathExistsInternal(cwd, '.planning/ROADMAP.md'), + state_exists: fs.existsSync(path.join(planningDir(cwd), 'STATE.md')), + roadmap_exists: fs.existsSync(path.join(planningDir(cwd), 'ROADMAP.md')), project_exists: pathExistsInternal(cwd, '.planning/PROJECT.md'), - planning_exists: pathExistsInternal(cwd, '.planning'), + planning_exists: fs.existsSync(planningRoot(cwd)), // File paths - state_path: '.planning/STATE.md', - roadmap_path: '.planning/ROADMAP.md', + state_path: toPosixPath(path.relative(cwd, path.join(planningDir(cwd), 'STATE.md'))), + roadmap_path: toPosixPath(path.relative(cwd, path.join(planningDir(cwd), 'ROADMAP.md'))), project_path: '.planning/PROJECT.md', // Agent state @@ -329,7 +477,7 @@ function cmdInitResume(cwd, raw) { commit_docs: config.commit_docs, }; - output(result, raw); + output(withProjectRoot(cwd, result), raw); } function cmdInitVerifyWork(cwd, phase, raw) { @@ -338,7 +486,28 @@ function cmdInitVerifyWork(cwd, phase, raw) { } const config = loadConfig(cwd); - const phaseInfo = findPhaseInternal(cwd, phase); + let phaseInfo = findPhaseInternal(cwd, phase); + + // Fallback to ROADMAP.md if no phase directory exists yet + if (!phaseInfo) { + const roadmapPhase = getRoadmapPhaseInternal(cwd, phase); + if (roadmapPhase?.found) { + const phaseName = roadmapPhase.phase_name; + phaseInfo = { + found: true, + directory: null, + phase_number: roadmapPhase.phase_number, + phase_name: phaseName, + phase_slug: phaseName ? phaseName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') : null, + plans: [], + summaries: [], + incomplete_plans: [], + has_research: false, + has_context: false, + has_verification: false, + }; + } + } const result = { // Models @@ -358,13 +527,36 @@ function cmdInitVerifyWork(cwd, phase, raw) { has_verification: phaseInfo?.has_verification || false, }; - output(result, raw); + output(withProjectRoot(cwd, result), raw); } function cmdInitPhaseOp(cwd, phase, raw) { const config = loadConfig(cwd); let phaseInfo = findPhaseInternal(cwd, phase); + // If the only disk match comes from an archived milestone, prefer the + // current milestone's ROADMAP entry so discuss-phase and similar flows + // don't attach to shipped work that reused the same phase number. + if (phaseInfo?.archived) { + const roadmapPhase = getRoadmapPhaseInternal(cwd, phase); + if (roadmapPhase?.found) { + const phaseName = roadmapPhase.phase_name; + phaseInfo = { + found: true, + directory: null, + phase_number: roadmapPhase.phase_number, + phase_name: phaseName, + phase_slug: phaseName ? phaseName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') : null, + plans: [], + summaries: [], + incomplete_plans: [], + has_research: false, + has_context: false, + has_verification: false, + }; + } + } + // Fallback to ROADMAP.md if no directory exists (e.g., Plans: TBD) if (!phaseInfo) { const roadmapPhase = getRoadmapPhaseInternal(cwd, phase); @@ -390,6 +582,8 @@ function cmdInitPhaseOp(cwd, phase, raw) { // Config commit_docs: config.commit_docs, brave_search: config.brave_search, + firecrawl: config.firecrawl, + exa_search: config.exa_search, // Phase info phase_found: !!phaseInfo, @@ -397,23 +591,24 @@ function cmdInitPhaseOp(cwd, phase, raw) { phase_number: phaseInfo?.phase_number || null, phase_name: phaseInfo?.phase_name || null, phase_slug: phaseInfo?.phase_slug || null, - padded_phase: phaseInfo?.phase_number?.padStart(2, '0') || null, + padded_phase: phaseInfo?.phase_number ? normalizePhaseName(phaseInfo.phase_number) : null, // Existing artifacts has_research: phaseInfo?.has_research || false, has_context: phaseInfo?.has_context || false, has_plans: (phaseInfo?.plans?.length || 0) > 0, has_verification: phaseInfo?.has_verification || false, + has_reviews: phaseInfo?.has_reviews || false, plan_count: phaseInfo?.plans?.length || 0, // File existence - roadmap_exists: pathExistsInternal(cwd, '.planning/ROADMAP.md'), - planning_exists: pathExistsInternal(cwd, '.planning'), + roadmap_exists: fs.existsSync(path.join(planningDir(cwd), 'ROADMAP.md')), + planning_exists: fs.existsSync(planningDir(cwd)), // File paths - state_path: '.planning/STATE.md', - roadmap_path: '.planning/ROADMAP.md', - requirements_path: '.planning/REQUIREMENTS.md', + state_path: toPosixPath(path.relative(cwd, path.join(planningDir(cwd), 'STATE.md'))), + roadmap_path: toPosixPath(path.relative(cwd, path.join(planningDir(cwd), 'ROADMAP.md'))), + requirements_path: toPosixPath(path.relative(cwd, path.join(planningDir(cwd), 'REQUIREMENTS.md'))), }; if (phaseInfo?.directory) { @@ -436,10 +631,14 @@ function cmdInitPhaseOp(cwd, phase, raw) { if (uatFile) { result.uat_path = toPosixPath(path.join(phaseInfo.directory, uatFile)); } - } catch {} + const reviewsFile = files.find(f => f.endsWith('-REVIEWS.md') || f === 'REVIEWS.md'); + if (reviewsFile) { + result.reviews_path = toPosixPath(path.join(phaseInfo.directory, reviewsFile)); + } + } catch { /* intentionally empty */ } } - output(result, raw); + output(withProjectRoot(cwd, result), raw); } function cmdInitTodos(cwd, area, raw) { @@ -447,7 +646,7 @@ function cmdInitTodos(cwd, area, raw) { const now = new Date(); // List todos (reuse existing logic) - const pendingDir = path.join(cwd, '.planning', 'todos', 'pending'); + const pendingDir = path.join(planningDir(cwd), 'todos', 'pending'); let count = 0; const todos = []; @@ -469,11 +668,11 @@ function cmdInitTodos(cwd, area, raw) { created: createdMatch ? createdMatch[1].trim() : 'unknown', title: titleMatch ? titleMatch[1].trim() : 'Untitled', area: todoArea, - path: '.planning/todos/pending/' + file, + path: toPosixPath(path.relative(cwd, path.join(planningDir(cwd), 'todos', 'pending', file))), }); - } catch {} + } catch { /* intentionally empty */ } } - } catch {} + } catch { /* intentionally empty */ } const result = { // Config @@ -489,16 +688,16 @@ function cmdInitTodos(cwd, area, raw) { area_filter: area || null, // Paths - pending_dir: '.planning/todos/pending', - completed_dir: '.planning/todos/completed', + pending_dir: toPosixPath(path.relative(cwd, path.join(planningDir(cwd), 'todos', 'pending'))), + completed_dir: toPosixPath(path.relative(cwd, path.join(planningDir(cwd), 'todos', 'completed'))), // File existence - planning_exists: pathExistsInternal(cwd, '.planning'), - todos_dir_exists: pathExistsInternal(cwd, '.planning/todos'), - pending_dir_exists: pathExistsInternal(cwd, '.planning/todos/pending'), + planning_exists: fs.existsSync(planningDir(cwd)), + todos_dir_exists: fs.existsSync(path.join(planningDir(cwd), 'todos')), + pending_dir_exists: fs.existsSync(path.join(planningDir(cwd), 'todos', 'pending')), }; - output(result, raw); + output(withProjectRoot(cwd, result), raw); } function cmdInitMilestoneOp(cwd, raw) { @@ -508,7 +707,7 @@ function cmdInitMilestoneOp(cwd, raw) { // Count phases let phaseCount = 0; let completedPhases = 0; - const phasesDir = path.join(cwd, '.planning', 'phases'); + const phasesDir = path.join(planningDir(cwd), 'phases'); try { const entries = fs.readdirSync(phasesDir, { withFileTypes: true }); const dirs = entries.filter(e => e.isDirectory()).map(e => e.name); @@ -520,18 +719,18 @@ function cmdInitMilestoneOp(cwd, raw) { const phaseFiles = fs.readdirSync(path.join(phasesDir, dir)); const hasSummary = phaseFiles.some(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md'); if (hasSummary) completedPhases++; - } catch {} + } catch { /* intentionally empty */ } } - } catch {} + } catch { /* intentionally empty */ } // Check archive - const archiveDir = path.join(cwd, '.planning', 'archive'); + const archiveDir = path.join(planningRoot(cwd), 'archive'); let archivedMilestones = []; try { archivedMilestones = fs.readdirSync(archiveDir, { withFileTypes: true }) .filter(e => e.isDirectory()) .map(e => e.name); - } catch {} + } catch { /* intentionally empty */ } const result = { // Config @@ -553,24 +752,24 @@ function cmdInitMilestoneOp(cwd, raw) { // File existence project_exists: pathExistsInternal(cwd, '.planning/PROJECT.md'), - roadmap_exists: pathExistsInternal(cwd, '.planning/ROADMAP.md'), - state_exists: pathExistsInternal(cwd, '.planning/STATE.md'), - archive_exists: pathExistsInternal(cwd, '.planning/archive'), - phases_dir_exists: pathExistsInternal(cwd, '.planning/phases'), + roadmap_exists: fs.existsSync(path.join(planningDir(cwd), 'ROADMAP.md')), + state_exists: fs.existsSync(path.join(planningDir(cwd), 'STATE.md')), + archive_exists: fs.existsSync(path.join(planningRoot(cwd), 'archive')), + phases_dir_exists: fs.existsSync(path.join(planningDir(cwd), 'phases')), }; - output(result, raw); + output(withProjectRoot(cwd, result), raw); } function cmdInitMapCodebase(cwd, raw) { const config = loadConfig(cwd); // Check for existing codebase maps - const codebaseDir = path.join(cwd, '.planning', 'codebase'); + const codebaseDir = path.join(planningRoot(cwd), 'codebase'); let existingMaps = []; try { existingMaps = fs.readdirSync(codebaseDir).filter(f => f.endsWith('.md')); - } catch {} + } catch { /* intentionally empty */ } const result = { // Models @@ -593,27 +792,300 @@ function cmdInitMapCodebase(cwd, raw) { codebase_dir_exists: pathExistsInternal(cwd, '.planning/codebase'), }; - output(result, raw); + output(withProjectRoot(cwd, result), raw); +} + +function cmdInitManager(cwd, raw) { + const config = loadConfig(cwd); + const milestone = getMilestoneInfo(cwd); + + // Use planningPaths for forward-compatibility with workstream scoping (#1268) + const paths = planningPaths(cwd); + + // Validate prerequisites + if (!fs.existsSync(paths.roadmap)) { + error('No ROADMAP.md found. Run /gsd-new-milestone first.'); + } + if (!fs.existsSync(paths.state)) { + error('No STATE.md found. Run /gsd-new-milestone first.'); + } + const rawContent = fs.readFileSync(paths.roadmap, 'utf-8'); + const content = extractCurrentMilestone(rawContent, cwd); + const phasesDir = paths.phases; + const isDirInMilestone = getMilestonePhaseFilter(cwd); + + const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:\s*([^\n]+)/gi; + const phases = []; + let match; + + while ((match = phasePattern.exec(content)) !== null) { + const phaseNum = match[1]; + const phaseName = match[2].replace(/\(INSERTED\)/i, '').trim(); + + const sectionStart = match.index; + const restOfContent = content.slice(sectionStart); + const nextHeader = restOfContent.match(/\n#{2,4}\s+Phase\s+\d/i); + const sectionEnd = nextHeader ? sectionStart + nextHeader.index : content.length; + const section = content.slice(sectionStart, sectionEnd); + + const goalMatch = section.match(/\*\*Goal(?::\*\*|\*\*:)\s*([^\n]+)/i); + const goal = goalMatch ? goalMatch[1].trim() : null; + + const dependsMatch = section.match(/\*\*Depends on(?::\*\*|\*\*:)\s*([^\n]+)/i); + const depends_on = dependsMatch ? dependsMatch[1].trim() : null; + + const normalized = normalizePhaseName(phaseNum); + let diskStatus = 'no_directory'; + let planCount = 0; + let summaryCount = 0; + let hasContext = false; + let hasResearch = false; + let lastActivity = null; + let isActive = false; + + try { + const entries = fs.readdirSync(phasesDir, { withFileTypes: true }); + const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).filter(isDirInMilestone); + const dirMatch = dirs.find(d => d.startsWith(normalized + '-') || d === normalized); + + if (dirMatch) { + const fullDir = path.join(phasesDir, dirMatch); + const phaseFiles = fs.readdirSync(fullDir); + planCount = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md').length; + summaryCount = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md').length; + hasContext = phaseFiles.some(f => f.endsWith('-CONTEXT.md') || f === 'CONTEXT.md'); + hasResearch = phaseFiles.some(f => f.endsWith('-RESEARCH.md') || f === 'RESEARCH.md'); + + if (summaryCount >= planCount && planCount > 0) diskStatus = 'complete'; + else if (summaryCount > 0) diskStatus = 'partial'; + else if (planCount > 0) diskStatus = 'planned'; + else if (hasResearch) diskStatus = 'researched'; + else if (hasContext) diskStatus = 'discussed'; + else diskStatus = 'empty'; + + // Activity detection: check most recent file mtime + const now = Date.now(); + let newestMtime = 0; + for (const f of phaseFiles) { + try { + const stat = fs.statSync(path.join(fullDir, f)); + if (stat.mtimeMs > newestMtime) newestMtime = stat.mtimeMs; + } catch { /* intentionally empty */ } + } + if (newestMtime > 0) { + lastActivity = new Date(newestMtime).toISOString(); + isActive = (now - newestMtime) < 300000; // 5 minutes + } + } + } catch { /* intentionally empty */ } + + // Check ROADMAP checkbox status + const checkboxPattern = new RegExp(`-\\s*\\[(x| )\\]\\s*.*Phase\\s+${phaseNum.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[:\\s]`, 'i'); + const checkboxMatch = content.match(checkboxPattern); + const roadmapComplete = checkboxMatch ? checkboxMatch[1] === 'x' : false; + if (roadmapComplete && diskStatus !== 'complete') { + diskStatus = 'complete'; + } + + phases.push({ + number: phaseNum, + name: phaseName, + goal, + depends_on, + disk_status: diskStatus, + has_context: hasContext, + has_research: hasResearch, + plan_count: planCount, + summary_count: summaryCount, + roadmap_complete: roadmapComplete, + last_activity: lastActivity, + is_active: isActive, + }); + } + + // Compute display names: truncate to keep table aligned + const MAX_NAME_WIDTH = 20; + for (const phase of phases) { + if (phase.name.length > MAX_NAME_WIDTH) { + phase.display_name = phase.name.slice(0, MAX_NAME_WIDTH - 1) + '…'; + } else { + phase.display_name = phase.name; + } + } + + // Dependency satisfaction: check if all depends_on phases are complete + const completedNums = new Set(phases.filter(p => p.disk_status === 'complete').map(p => p.number)); + for (const phase of phases) { + if (!phase.depends_on || /^none$/i.test(phase.depends_on.trim())) { + phase.deps_satisfied = true; + } else { + // Parse "Phase 1, Phase 3" or "1, 3" formats + const depNums = phase.depends_on.match(/\d+(?:\.\d+)*/g) || []; + phase.deps_satisfied = depNums.every(n => completedNums.has(n)); + phase.dep_phases = depNums; + } + } + + // Compact dependency display for dashboard + for (const phase of phases) { + phase.deps_display = (phase.dep_phases && phase.dep_phases.length > 0) + ? phase.dep_phases.join(',') + : '—'; + } + + // Sliding window: discuss is sequential — only the first undiscussed phase is available + let foundNextToDiscuss = false; + for (const phase of phases) { + if (!foundNextToDiscuss && (phase.disk_status === 'empty' || phase.disk_status === 'no_directory')) { + phase.is_next_to_discuss = true; + foundNextToDiscuss = true; + } else { + phase.is_next_to_discuss = false; + } + } + + // Check for WAITING.json signal + let waitingSignal = null; + try { + const waitingPath = path.join(cwd, '.planning', 'WAITING.json'); + if (fs.existsSync(waitingPath)) { + waitingSignal = JSON.parse(fs.readFileSync(waitingPath, 'utf-8')); + } + } catch { /* intentionally empty */ } + + // Compute recommended actions (execute > plan > discuss) + const recommendedActions = []; + for (const phase of phases) { + if (phase.disk_status === 'complete') continue; + + if (phase.disk_status === 'planned' && phase.deps_satisfied) { + recommendedActions.push({ + phase: phase.number, + phase_name: phase.name, + action: 'execute', + reason: `${phase.plan_count} plans ready, dependencies met`, + command: `/gsd-execute-phase ${phase.number}`, + }); + } else if (phase.disk_status === 'discussed' || phase.disk_status === 'researched') { + recommendedActions.push({ + phase: phase.number, + phase_name: phase.name, + action: 'plan', + reason: 'Context gathered, ready for planning', + command: `/gsd-plan-phase ${phase.number}`, + }); + } else if ((phase.disk_status === 'empty' || phase.disk_status === 'no_directory') && phase.is_next_to_discuss) { + recommendedActions.push({ + phase: phase.number, + phase_name: phase.name, + action: 'discuss', + reason: 'Unblocked, ready to gather context', + command: `/gsd-discuss-phase ${phase.number}`, + }); + } + } + + // Filter recommendations: no parallel execute/plan unless phases are independent + // Two phases are "independent" if neither depends on the other (directly or transitively) + const phaseMap = new Map(phases.map(p => [p.number, p])); + + function reaches(from, to, visited = new Set()) { + if (visited.has(from)) return false; + visited.add(from); + const p = phaseMap.get(from); + if (!p || !p.dep_phases || p.dep_phases.length === 0) return false; + if (p.dep_phases.includes(to)) return true; + return p.dep_phases.some(dep => reaches(dep, to, visited)); + } + + function hasDepRelationship(numA, numB) { + return reaches(numA, numB) || reaches(numB, numA); + } + + // Detect phases with active work (file modified in last 5 min) + const activeExecuting = phases.filter(p => + p.disk_status === 'partial' || + (p.disk_status === 'planned' && p.is_active) + ); + const activePlanning = phases.filter(p => + p.is_active && (p.disk_status === 'discussed' || p.disk_status === 'researched') + ); + + const filteredActions = recommendedActions.filter(action => { + if (action.action === 'execute' && activeExecuting.length > 0) { + // Only allow if independent of ALL actively-executing phases + return activeExecuting.every(active => !hasDepRelationship(action.phase, active.number)); + } + if (action.action === 'plan' && activePlanning.length > 0) { + // Only allow if independent of ALL actively-planning phases + return activePlanning.every(active => !hasDepRelationship(action.phase, active.number)); + } + return true; + }); + + const completedCount = phases.filter(p => p.disk_status === 'complete').length; + const result = { + milestone_version: milestone.version, + milestone_name: milestone.name, + phases, + phase_count: phases.length, + completed_count: completedCount, + in_progress_count: phases.filter(p => ['partial', 'planned', 'discussed', 'researched'].includes(p.disk_status)).length, + recommended_actions: filteredActions, + waiting_signal: waitingSignal, + all_complete: completedCount === phases.length && phases.length > 0, + project_exists: pathExistsInternal(cwd, '.planning/PROJECT.md'), + roadmap_exists: true, + state_exists: true, + }; + + output(withProjectRoot(cwd, result), raw); } function cmdInitProgress(cwd, raw) { const config = loadConfig(cwd); const milestone = getMilestoneInfo(cwd); - // Analyze phases - const phasesDir = path.join(cwd, '.planning', 'phases'); + // Analyze phases — filter to current milestone and include ROADMAP-only phases + const phasesDir = path.join(planningDir(cwd), 'phases'); const phases = []; let currentPhase = null; let nextPhase = null; + // Build set of phases defined in ROADMAP for the current milestone + const roadmapPhaseNums = new Set(); + const roadmapPhaseNames = new Map(); + try { + const roadmapContent = extractCurrentMilestone( + fs.readFileSync(path.join(planningDir(cwd), 'ROADMAP.md'), 'utf-8'), cwd + ); + const headingPattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:\s*([^\n]+)/gi; + let hm; + while ((hm = headingPattern.exec(roadmapContent)) !== null) { + roadmapPhaseNums.add(hm[1]); + roadmapPhaseNames.set(hm[1], hm[2].replace(/\(INSERTED\)/i, '').trim()); + } + } catch { /* intentionally empty */ } + + const isDirInMilestone = getMilestonePhaseFilter(cwd); + const seenPhaseNums = new Set(); + try { const entries = fs.readdirSync(phasesDir, { withFileTypes: true }); - const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort(); + const dirs = entries.filter(e => e.isDirectory()).map(e => e.name) + .filter(isDirInMilestone) + .sort((a, b) => { + const pa = a.match(/^(\d+[A-Z]?(?:\.\d+)*)/i); + const pb = b.match(/^(\d+[A-Z]?(?:\.\d+)*)/i); + if (!pa || !pb) return a.localeCompare(b); + return parseInt(pa[1], 10) - parseInt(pb[1], 10); + }); for (const dir of dirs) { - const match = dir.match(/^(\d+(?:\.\d+)*)-?(.*)/); + const match = dir.match(/^(\d+[A-Z]?(?:\.\d+)*)-?(.*)/i); const phaseNumber = match ? match[1] : dir; const phaseName = match && match[2] ? match[2] : null; + seenPhaseNums.add(phaseNumber.replace(/^0+/, '') || '0'); const phasePath = path.join(phasesDir, dir); const phaseFiles = fs.readdirSync(phasePath); @@ -629,7 +1101,7 @@ function cmdInitProgress(cwd, raw) { const phaseInfo = { number: phaseNumber, name: phaseName, - directory: '.planning/phases/' + dir, + directory: toPosixPath(path.relative(cwd, path.join(planningDir(cwd), 'phases', dir))), status, plan_count: plans.length, summary_count: summaries.length, @@ -646,15 +1118,38 @@ function cmdInitProgress(cwd, raw) { nextPhase = phaseInfo; } } - } catch {} + } catch { /* intentionally empty */ } + + // Add phases defined in ROADMAP but not yet scaffolded to disk + for (const [num, name] of roadmapPhaseNames) { + const stripped = num.replace(/^0+/, '') || '0'; + if (!seenPhaseNums.has(stripped)) { + const phaseInfo = { + number: num, + name: name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, ''), + directory: null, + status: 'not_started', + plan_count: 0, + summary_count: 0, + has_research: false, + }; + phases.push(phaseInfo); + if (!nextPhase && !currentPhase) { + nextPhase = phaseInfo; + } + } + } + + // Re-sort phases by number after adding ROADMAP-only phases + phases.sort((a, b) => parseInt(a.number, 10) - parseInt(b.number, 10)); // Check for paused work let pausedAt = null; try { - const state = fs.readFileSync(path.join(cwd, '.planning', 'STATE.md'), 'utf-8'); + const state = fs.readFileSync(path.join(planningDir(cwd), 'STATE.md'), 'utf-8'); const pauseMatch = state.match(/\*\*Paused At:\*\*\s*(.+)/); if (pauseMatch) pausedAt = pauseMatch[1].trim(); - } catch {} + } catch { /* intentionally empty */ } const result = { // Models @@ -682,18 +1177,248 @@ function cmdInitProgress(cwd, raw) { // File existence project_exists: pathExistsInternal(cwd, '.planning/PROJECT.md'), - roadmap_exists: pathExistsInternal(cwd, '.planning/ROADMAP.md'), - state_exists: pathExistsInternal(cwd, '.planning/STATE.md'), + roadmap_exists: fs.existsSync(path.join(planningDir(cwd), 'ROADMAP.md')), + state_exists: fs.existsSync(path.join(planningDir(cwd), 'STATE.md')), // File paths - state_path: '.planning/STATE.md', - roadmap_path: '.planning/ROADMAP.md', + state_path: toPosixPath(path.relative(cwd, path.join(planningDir(cwd), 'STATE.md'))), + roadmap_path: toPosixPath(path.relative(cwd, path.join(planningDir(cwd), 'ROADMAP.md'))), project_path: '.planning/PROJECT.md', - config_path: '.planning/config.json', + config_path: toPosixPath(path.relative(cwd, path.join(planningDir(cwd), 'config.json'))), + }; + + output(withProjectRoot(cwd, result), raw); +} + +/** + * Detect child git repos in a directory (one level deep). + * Returns array of { name, path, has_uncommitted } objects. + */ +function detectChildRepos(dir) { + const repos = []; + let entries; + try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return repos; } + for (const entry of entries) { + if (!entry.isDirectory()) continue; + if (entry.name.startsWith('.')) continue; + const fullPath = path.join(dir, entry.name); + const gitDir = path.join(fullPath, '.git'); + if (fs.existsSync(gitDir)) { + let hasUncommitted = false; + try { + const status = execSync('git status --porcelain', { cwd: fullPath, encoding: 'utf8', timeout: 5000 }); + hasUncommitted = status.trim().length > 0; + } catch { /* best-effort */ } + repos.push({ name: entry.name, path: fullPath, has_uncommitted: hasUncommitted }); + } + } + return repos; +} + +function cmdInitNewWorkspace(cwd, raw) { + const homedir = process.env.HOME || require('os').homedir(); + const defaultBase = path.join(homedir, 'gsd-workspaces'); + + // Detect child git repos for interactive selection + const childRepos = detectChildRepos(cwd); + + // Check if git worktree is available + let worktreeAvailable = false; + try { + execSync('git --version', { encoding: 'utf8', timeout: 5000, stdio: 'pipe' }); + worktreeAvailable = true; + } catch { /* no git at all */ } + + const result = { + default_workspace_base: defaultBase, + child_repos: childRepos, + child_repo_count: childRepos.length, + worktree_available: worktreeAvailable, + is_git_repo: pathExistsInternal(cwd, '.git'), + cwd_repo_name: path.basename(cwd), + }; + + output(withProjectRoot(cwd, result), raw); +} + +function cmdInitListWorkspaces(cwd, raw) { + const homedir = process.env.HOME || require('os').homedir(); + const defaultBase = path.join(homedir, 'gsd-workspaces'); + + const workspaces = []; + if (fs.existsSync(defaultBase)) { + let entries; + try { entries = fs.readdirSync(defaultBase, { withFileTypes: true }); } catch { entries = []; } + for (const entry of entries) { + if (!entry.isDirectory()) continue; + const wsPath = path.join(defaultBase, entry.name); + const manifestPath = path.join(wsPath, 'WORKSPACE.md'); + if (!fs.existsSync(manifestPath)) continue; + + let repoCount = 0; + let hasProject = false; + let strategy = 'unknown'; + try { + const manifest = fs.readFileSync(manifestPath, 'utf8'); + const strategyMatch = manifest.match(/^Strategy:\s*(.+)$/m); + if (strategyMatch) strategy = strategyMatch[1].trim(); + // Count table rows (lines starting with |, excluding header and separator) + const tableRows = manifest.split('\n').filter(l => l.match(/^\|\s*\w/) && !l.includes('Repo') && !l.includes('---')); + repoCount = tableRows.length; + } catch { /* best-effort */ } + hasProject = fs.existsSync(path.join(wsPath, '.planning', 'PROJECT.md')); + + workspaces.push({ + name: entry.name, + path: wsPath, + repo_count: repoCount, + strategy, + has_project: hasProject, + }); + } + } + + const result = { + workspace_base: defaultBase, + workspaces, + workspace_count: workspaces.length, + }; + + output(result, raw); +} + +function cmdInitRemoveWorkspace(cwd, name, raw) { + const homedir = process.env.HOME || require('os').homedir(); + const defaultBase = path.join(homedir, 'gsd-workspaces'); + + if (!name) { + error('workspace name required for init remove-workspace'); + } + + const wsPath = path.join(defaultBase, name); + const manifestPath = path.join(wsPath, 'WORKSPACE.md'); + + if (!fs.existsSync(wsPath)) { + error(`Workspace not found: ${wsPath}`); + } + + // Parse manifest for repo info + const repos = []; + let strategy = 'unknown'; + if (fs.existsSync(manifestPath)) { + try { + const manifest = fs.readFileSync(manifestPath, 'utf8'); + const strategyMatch = manifest.match(/^Strategy:\s*(.+)$/m); + if (strategyMatch) strategy = strategyMatch[1].trim(); + + // Parse table rows for repo names and source paths + const lines = manifest.split('\n'); + for (const line of lines) { + const match = line.match(/^\|\s*(\S+)\s*\|\s*(\S+)\s*\|\s*(\S+)\s*\|\s*(\S+)\s*\|$/); + if (match && match[1] !== 'Repo' && !match[1].includes('---')) { + repos.push({ name: match[1], source: match[2], branch: match[3], strategy: match[4] }); + } + } + } catch { /* best-effort */ } + } + + // Check for uncommitted changes in workspace repos + const dirtyRepos = []; + for (const repo of repos) { + const repoPath = path.join(wsPath, repo.name); + if (!fs.existsSync(repoPath)) continue; + try { + const status = execSync('git status --porcelain', { cwd: repoPath, encoding: 'utf8', timeout: 5000, stdio: 'pipe' }); + if (status.trim().length > 0) { + dirtyRepos.push(repo.name); + } + } catch { /* best-effort */ } + } + + const result = { + workspace_name: name, + workspace_path: wsPath, + has_manifest: fs.existsSync(manifestPath), + strategy, + repos, + repo_count: repos.length, + dirty_repos: dirtyRepos, + has_dirty_repos: dirtyRepos.length > 0, }; output(result, raw); } +/** + * Build a formatted agent skills block for injection into task() prompts. + * + * Reads `config.agent_skills[agentType]` and validates each skill path exists + * within the project root. Returns a formatted `` block or empty + * string if no skills are configured. + * + * @param {object} config - Loaded project config + * @param {string} agentType - The agent type (e.g., 'gsd-executor', 'gsd-planner') + * @param {string} projectRoot - Absolute path to project root (for path validation) + * @returns {string} Formatted skills block or empty string + */ +function buildAgentSkillsBlock(config, agentType, projectRoot) { + const { validatePath } = require('./security.cjs'); + + if (!config || !config.agent_skills || !agentType) return ''; + + let skillPaths = config.agent_skills[agentType]; + if (!skillPaths) return ''; + + // Normalize single string to array + if (typeof skillPaths === 'string') skillPaths = [skillPaths]; + if (!Array.isArray(skillPaths) || skillPaths.length === 0) return ''; + + const validPaths = []; + for (const skillPath of skillPaths) { + if (typeof skillPath !== 'string') continue; + + // Validate path safety — must resolve within project root + const pathCheck = validatePath(skillPath, projectRoot); + if (!pathCheck.safe) { + process.stderr.write(`[agent-skills] WARNING: Skipping unsafe path "${skillPath}": ${pathCheck.error}\n`); + continue; + } + + // Check that the skill directory and SKILL.md exist + const skillMdPath = path.join(projectRoot, skillPath, 'SKILL.md'); + if (!fs.existsSync(skillMdPath)) { + process.stderr.write(`[agent-skills] WARNING: skill not found at "${skillPath}/SKILL.md" — skipping\n`); + continue; + } + + validPaths.push(skillPath); + } + + if (validPaths.length === 0) return ''; + + const lines = validPaths.map(p => `- @${p}/SKILL.md`).join('\n'); + return `\nRead these user-configured skills:\n${lines}\n`; +} + +/** + * Command: output the agent skills block for a given agent type. + * Used by workflows: SKILLS=$(node "$TOOLS" agent-skills gsd-executor 2>/dev/null) + */ +function cmdAgentSkills(cwd, agentType, raw) { + if (!agentType) { + // No agent type — output empty string silently + output('', raw, ''); + return; + } + + const config = loadConfig(cwd); + const block = buildAgentSkillsBlock(config, agentType, cwd); + // Output raw text (not JSON) so workflows can embed it directly + if (block) { + process.stdout.write(block); + } + process.exit(0); +} + module.exports = { cmdInitExecutePhase, cmdInitPlanPhase, @@ -707,4 +1432,11 @@ module.exports = { cmdInitMilestoneOp, cmdInitMapCodebase, cmdInitProgress, + cmdInitManager, + cmdInitNewWorkspace, + cmdInitListWorkspaces, + cmdInitRemoveWorkspace, + detectChildRepos, + buildAgentSkillsBlock, + cmdAgentSkills, }; diff --git a/gsd-opencode/get-shit-done/bin/lib/milestone.cjs b/gsd-opencode/get-shit-done/bin/lib/milestone.cjs index efc0a18..a29a07e 100644 --- a/gsd-opencode/get-shit-done/bin/lib/milestone.cjs +++ b/gsd-opencode/get-shit-done/bin/lib/milestone.cjs @@ -4,9 +4,9 @@ const fs = require('fs'); const path = require('path'); -const { escapeRegex, getMilestonePhaseFilter, output, error } = require('./core.cjs'); +const { escapeRegex, getMilestonePhaseFilter, extractOneLinerFromBody, normalizeMd, planningPaths, output, error } = require('./core.cjs'); const { extractFrontmatter } = require('./frontmatter.cjs'); -const { writeStateMd } = require('./state.cjs'); +const { writeStateMd, stateReplaceFieldWithFallback } = require('./state.cjs'); function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) { if (!reqIdsRaw || reqIdsRaw.length === 0) { @@ -25,7 +25,7 @@ function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) { error('no valid requirement IDs found'); } - const reqPath = path.join(cwd, '.planning', 'REQUIREMENTS.md'); + const reqPath = planningPaths(cwd).requirements; if (!fs.existsSync(reqPath)) { output({ updated: false, reason: 'REQUIREMENTS.md not found', ids: reqIds }, raw, 'no requirements file'); return; @@ -33,6 +33,7 @@ function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) { let reqContent = fs.readFileSync(reqPath, 'utf-8'); const updated = []; + const alreadyComplete = []; const notFound = []; for (const reqId of reqIds) { @@ -60,7 +61,14 @@ function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) { if (found) { updated.push(reqId); } else { - notFound.push(reqId); + // Check if already complete before declaring not_found + const doneCheckbox = new RegExp(`-\\s*\\[x\\]\\s*\\*\\*${reqEscaped}\\*\\*`, 'gi'); + const doneTable = new RegExp(`\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|\\s*Complete\\s*\\|`, 'gi'); + if (doneCheckbox.test(reqContent) || doneTable.test(reqContent)) { + alreadyComplete.push(reqId); + } else { + notFound.push(reqId); + } } } @@ -71,6 +79,7 @@ function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) { output({ updated: updated.length > 0, marked_complete: updated, + already_complete: alreadyComplete, not_found: notFound, total: reqIds.length, }, raw, `${updated.length}/${reqIds.length} requirements marked complete`); @@ -81,12 +90,12 @@ function cmdMilestoneComplete(cwd, version, options, raw) { error('version required for milestone complete (e.g., v1.0)'); } - const roadmapPath = path.join(cwd, '.planning', 'ROADMAP.md'); - const reqPath = path.join(cwd, '.planning', 'REQUIREMENTS.md'); - const statePath = path.join(cwd, '.planning', 'STATE.md'); + const roadmapPath = planningPaths(cwd).roadmap; + const reqPath = planningPaths(cwd).requirements; + const statePath = planningPaths(cwd).state; const milestonesPath = path.join(cwd, '.planning', 'MILESTONES.md'); const archiveDir = path.join(cwd, '.planning', 'milestones'); - const phasesDir = path.join(cwd, '.planning', 'phases'); + const phasesDir = planningPaths(cwd).phases; const today = new Date().toISOString().split('T')[0]; const milestoneName = options.name || version; @@ -122,16 +131,24 @@ function cmdMilestoneComplete(cwd, version, options, raw) { try { const content = fs.readFileSync(path.join(phasesDir, dir, s), 'utf-8'); const fm = extractFrontmatter(content); - if (fm['one-liner']) { - accomplishments.push(fm['one-liner']); + const oneLiner = fm['one-liner'] || extractOneLinerFromBody(content); + if (oneLiner) { + accomplishments.push(oneLiner); + } + // Count tasks: prefer **Tasks:** N from Performance section, + // then ]/gi) || []; + const mdTaskMatches = content.match(/##\s*task\s*\d+/gi) || []; + totalTasks += xmlTaskMatches.length || mdTaskMatches.length; } - // Count tasks - const taskMatches = content.match(/##\s*task\s*\d+/gi) || []; - totalTasks += taskMatches.length; - } catch {} + } catch { /* intentionally empty */ } } } - } catch {} + } catch { /* intentionally empty */ } // Archive ROADMAP.md if (fs.existsSync(roadmapPath)) { @@ -160,38 +177,32 @@ function cmdMilestoneComplete(cwd, version, options, raw) { const existing = fs.readFileSync(milestonesPath, 'utf-8'); if (!existing.trim()) { // Empty file — treat like new - fs.writeFileSync(milestonesPath, `# Milestones\n\n${milestoneEntry}`, 'utf-8'); + fs.writeFileSync(milestonesPath, normalizeMd(`# Milestones\n\n${milestoneEntry}`), 'utf-8'); } else { // Insert after the header line(s) for reverse chronological order (newest first) const headerMatch = existing.match(/^(#{1,3}\s+[^\n]*\n\n?)/); if (headerMatch) { const header = headerMatch[1]; const rest = existing.slice(header.length); - fs.writeFileSync(milestonesPath, header + milestoneEntry + rest, 'utf-8'); + fs.writeFileSync(milestonesPath, normalizeMd(header + milestoneEntry + rest), 'utf-8'); } else { // No recognizable header — prepend the entry - fs.writeFileSync(milestonesPath, milestoneEntry + existing, 'utf-8'); + fs.writeFileSync(milestonesPath, normalizeMd(milestoneEntry + existing), 'utf-8'); } } } else { - fs.writeFileSync(milestonesPath, `# Milestones\n\n${milestoneEntry}`, 'utf-8'); + fs.writeFileSync(milestonesPath, normalizeMd(`# Milestones\n\n${milestoneEntry}`), 'utf-8'); } - // Update STATE.md + // Update STATE.md — use shared helpers that handle both **bold:** and plain Field: formats if (fs.existsSync(statePath)) { let stateContent = fs.readFileSync(statePath, 'utf-8'); - stateContent = stateContent.replace( - /(\*\*Status:\*\*\s*).*/, - `$1${version} milestone complete` - ); - stateContent = stateContent.replace( - /(\*\*Last Activity:\*\*\s*).*/, - `$1${today}` - ); - stateContent = stateContent.replace( - /(\*\*Last Activity Description:\*\*\s*).*/, - `$1${version} milestone completed and archived` - ); + + stateContent = stateReplaceFieldWithFallback(stateContent, 'Status', null, `${version} milestone complete`); + stateContent = stateReplaceFieldWithFallback(stateContent, 'Last Activity', 'Last activity', today); + stateContent = stateReplaceFieldWithFallback(stateContent, 'Last Activity Description', null, + `${version} milestone completed and archived`); + writeStateMd(statePath, stateContent, cwd); } @@ -211,7 +222,7 @@ function cmdMilestoneComplete(cwd, version, options, raw) { archivedCount++; } phasesArchived = archivedCount > 0; - } catch {} + } catch { /* intentionally empty */ } } const result = { diff --git a/gsd-opencode/get-shit-done/bin/lib/model-profiles.cjs b/gsd-opencode/get-shit-done/bin/lib/model-profiles.cjs new file mode 100644 index 0000000..3574562 --- /dev/null +++ b/gsd-opencode/get-shit-done/bin/lib/model-profiles.cjs @@ -0,0 +1,68 @@ +/** + * Mapping of GSD agent to model for each profile. + * + * Should be in sync with the profiles table in `get-shit-done/references/model-profiles.md`. But + * possibly worth making this the single source of truth at some point, and removing the markdown + * reference table in favor of programmatically determining the model to use for an agent (which + * would be faster, use fewer tokens, and be less error-prone). + */ +const MODEL_PROFILES = { + 'gsd-planner': { quality: 'opus', balanced: 'opus', budget: 'sonnet' }, + 'gsd-roadmapper': { quality: 'opus', balanced: 'sonnet', budget: 'sonnet' }, + 'gsd-executor': { quality: 'opus', balanced: 'sonnet', budget: 'sonnet' }, + 'gsd-phase-researcher': { quality: 'opus', balanced: 'sonnet', budget: 'haiku' }, + 'gsd-project-researcher': { quality: 'opus', balanced: 'sonnet', budget: 'haiku' }, + 'gsd-research-synthesizer': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' }, + 'gsd-debugger': { quality: 'opus', balanced: 'sonnet', budget: 'sonnet' }, + 'gsd-codebase-mapper': { quality: 'sonnet', balanced: 'haiku', budget: 'haiku' }, + 'gsd-verifier': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' }, + 'gsd-plan-checker': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' }, + 'gsd-integration-checker': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' }, + 'gsd-nyquist-auditor': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' }, + 'gsd-ui-researcher': { quality: 'opus', balanced: 'sonnet', budget: 'haiku' }, + 'gsd-ui-checker': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' }, + 'gsd-ui-auditor': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' }, +}; +const VALID_PROFILES = Object.keys(MODEL_PROFILES['gsd-planner']); + +/** + * Formats the agent-to-model mapping as a human-readable table (in string format). + * + * @param {Object} agentToModelMap - A mapping from agent to model + * @returns {string} A formatted table string + */ +function formatAgentToModelMapAsTable(agentToModelMap) { + const agentWidth = Math.max('Agent'.length, ...Object.keys(agentToModelMap).map((a) => a.length)); + const modelWidth = Math.max( + 'Model'.length, + ...Object.values(agentToModelMap).map((m) => m.length) + ); + const sep = '─'.repeat(agentWidth + 2) + '┼' + '─'.repeat(modelWidth + 2); + const header = ' ' + 'Agent'.padEnd(agentWidth) + ' │ ' + 'Model'.padEnd(modelWidth); + let agentToModelTable = header + '\n' + sep + '\n'; + for (const [agent, model] of Object.entries(agentToModelMap)) { + agentToModelTable += ' ' + agent.padEnd(agentWidth) + ' │ ' + model.padEnd(modelWidth) + '\n'; + } + return agentToModelTable; +} + +/** + * Returns a mapping from agent to model for the given model profile. + * + * @param {string} normalizedProfile - The normalized (lowercase and trimmed) profile name + * @returns {Object} A mapping from agent to model for the given profile + */ +function getAgentToModelMapForProfile(normalizedProfile) { + const agentToModelMap = {}; + for (const [agent, profileToModelMap] of Object.entries(MODEL_PROFILES)) { + agentToModelMap[agent] = profileToModelMap[normalizedProfile]; + } + return agentToModelMap; +} + +module.exports = { + MODEL_PROFILES, + VALID_PROFILES, + formatAgentToModelMapAsTable, + getAgentToModelMapForProfile, +}; diff --git a/gsd-opencode/get-shit-done/bin/lib/phase.cjs b/gsd-opencode/get-shit-done/bin/lib/phase.cjs index e544e2e..9fab260 100644 --- a/gsd-opencode/get-shit-done/bin/lib/phase.cjs +++ b/gsd-opencode/get-shit-done/bin/lib/phase.cjs @@ -4,12 +4,12 @@ const fs = require('fs'); const path = require('path'); -const { escapeRegex, normalizePhaseName, comparePhaseNum, findPhaseInternal, getArchivedPhaseDirs, generateSlugInternal, getMilestonePhaseFilter, toPosixPath, output, error } = require('./core.cjs'); +const { escapeRegex, loadConfig, normalizePhaseName, comparePhaseNum, findPhaseInternal, getArchivedPhaseDirs, generateSlugInternal, getMilestonePhaseFilter, stripShippedMilestones, extractCurrentMilestone, replaceInCurrentMilestone, toPosixPath, planningDir, output, error, readSubdirectories } = require('./core.cjs'); const { extractFrontmatter } = require('./frontmatter.cjs'); -const { writeStateMd } = require('./state.cjs'); +const { writeStateMd, stateExtractField, stateReplaceField, stateReplaceFieldWithFallback } = require('./state.cjs'); function cmdPhasesList(cwd, options, raw) { - const phasesDir = path.join(cwd, '.planning', 'phases'); + const phasesDir = path.join(planningDir(cwd), 'phases'); const { type, phase, includeArchived } = options; // If no phases directory, return empty @@ -85,7 +85,7 @@ function cmdPhasesList(cwd, options, raw) { } function cmdPhaseNextDecimal(cwd, basePhase, raw) { - const phasesDir = path.join(cwd, '.planning', 'phases'); + const phasesDir = path.join(planningDir(cwd), 'phases'); const normalized = normalizePhaseName(basePhase); // Check if phases directory exists @@ -154,7 +154,7 @@ function cmdFindPhase(cwd, phase, raw) { error('phase identifier required'); } - const phasesDir = path.join(cwd, '.planning', 'phases'); + const phasesDir = path.join(planningDir(cwd), 'phases'); const normalized = normalizePhaseName(phase); const notFound = { found: false, directory: null, phase_number: null, phase_name: null, plans: [], summaries: [] }; @@ -180,7 +180,7 @@ function cmdFindPhase(cwd, phase, raw) { const result = { found: true, - directory: toPosixPath(path.join('.planning', 'phases', match)), + directory: toPosixPath(path.join(path.relative(cwd, planningDir(cwd)), 'phases', match)), phase_number: phaseNumber, phase_name: phaseName, plans, @@ -203,7 +203,7 @@ function cmdPhasePlanIndex(cwd, phase, raw) { error('phase required for phase-plan-index'); } - const phasesDir = path.join(cwd, '.planning', 'phases'); + const phasesDir = path.join(planningDir(cwd), 'phases'); const normalized = normalizePhaseName(phase); // Find phase directory @@ -308,60 +308,75 @@ function cmdPhasePlanIndex(cwd, phase, raw) { output(result, raw); } -function cmdPhaseAdd(cwd, description, raw) { +function cmdPhaseAdd(cwd, description, raw, customId) { if (!description) { error('description required for phase add'); } - const roadmapPath = path.join(cwd, '.planning', 'ROADMAP.md'); + const config = loadConfig(cwd); + const roadmapPath = path.join(planningDir(cwd), 'ROADMAP.md'); if (!fs.existsSync(roadmapPath)) { error('ROADMAP.md not found'); } - const content = fs.readFileSync(roadmapPath, 'utf-8'); + const rawContent = fs.readFileSync(roadmapPath, 'utf-8'); + const content = extractCurrentMilestone(rawContent, cwd); const slug = generateSlugInternal(description); - // Find highest integer phase number - const phasePattern = /#{2,4}\s*Phase\s+(\d+)[A-Z]?(?:\.\d+)*:/gi; - let maxPhase = 0; - let m; - while ((m = phasePattern.exec(content)) !== null) { - const num = parseInt(m[1], 10); - if (num > maxPhase) maxPhase = num; + let newPhaseId; + let dirName; + + if (customId || config.phase_naming === 'custom') { + // Custom phase naming: use provided ID or generate from description + newPhaseId = customId || slug.toUpperCase().replace(/-/g, '-'); + if (!newPhaseId) error('--id required when phase_naming is "custom"'); + dirName = `${newPhaseId}-${slug}`; + } else { + // Sequential mode: find highest integer phase number (in current milestone only) + const phasePattern = /#{2,4}\s*Phase\s+(\d+)[A-Z]?(?:\.\d+)*:/gi; + let maxPhase = 0; + let m; + while ((m = phasePattern.exec(content)) !== null) { + const num = parseInt(m[1], 10); + if (num > maxPhase) maxPhase = num; + } + + newPhaseId = maxPhase + 1; + const paddedNum = String(newPhaseId).padStart(2, '0'); + dirName = `${paddedNum}-${slug}`; } - const newPhaseNum = maxPhase + 1; - const paddedNum = String(newPhaseNum).padStart(2, '0'); - const dirName = `${paddedNum}-${slug}`; - const dirPath = path.join(cwd, '.planning', 'phases', dirName); + const dirPath = path.join(planningDir(cwd), 'phases', dirName); // Create directory with .gitkeep so git tracks empty folders fs.mkdirSync(dirPath, { recursive: true }); fs.writeFileSync(path.join(dirPath, '.gitkeep'), ''); // Build phase entry - const phaseEntry = `\n### Phase ${newPhaseNum}: ${description}\n\n**Goal:** [To be planned]\n**Requirements**: TBD\n**Depends on:** Phase ${maxPhase}\n**Plans:** 0 plans\n\nPlans:\n- [ ] TBD (run /gsd-plan-phase ${newPhaseNum} to break down)\n`; + const dependsOn = config.phase_naming === 'custom' ? '' : `\n**Depends on:** Phase ${typeof newPhaseId === 'number' ? newPhaseId - 1 : 'TBD'}`; + const phaseEntry = `\n### Phase ${newPhaseId}: ${description}\n\n**Goal:** [To be planned]\n**Requirements**: TBD${dependsOn}\n**Plans:** 0 plans\n\nPlans:\n- [ ] TBD (run /gsd-plan-phase ${newPhaseId} to break down)\n`; // Find insertion point: before last "---" or at end let updatedContent; - const lastSeparator = content.lastIndexOf('\n---'); + const lastSeparator = rawContent.lastIndexOf('\n---'); if (lastSeparator > 0) { - updatedContent = content.slice(0, lastSeparator) + phaseEntry + content.slice(lastSeparator); + updatedContent = rawContent.slice(0, lastSeparator) + phaseEntry + rawContent.slice(lastSeparator); } else { - updatedContent = content + phaseEntry; + updatedContent = rawContent + phaseEntry; } fs.writeFileSync(roadmapPath, updatedContent, 'utf-8'); const result = { - phase_number: newPhaseNum, - padded: paddedNum, + phase_number: typeof newPhaseId === 'number' ? newPhaseId : String(newPhaseId), + padded: typeof newPhaseId === 'number' ? String(newPhaseId).padStart(2, '0') : String(newPhaseId), name: description, slug, - directory: `.planning/phases/${dirName}`, + directory: toPosixPath(path.join(path.relative(cwd, planningDir(cwd)), 'phases', dirName)), + naming_mode: config.phase_naming, }; - output(result, raw, paddedNum); + output(result, raw, result.padded); } function cmdPhaseInsert(cwd, afterPhase, description, raw) { @@ -369,12 +384,13 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) { error('after-phase and description required for phase insert'); } - const roadmapPath = path.join(cwd, '.planning', 'ROADMAP.md'); + const roadmapPath = path.join(planningDir(cwd), 'ROADMAP.md'); if (!fs.existsSync(roadmapPath)) { error('ROADMAP.md not found'); } - const content = fs.readFileSync(roadmapPath, 'utf-8'); + const rawContent = fs.readFileSync(roadmapPath, 'utf-8'); + const content = extractCurrentMilestone(rawContent, cwd); const slug = generateSlugInternal(description); // Normalize input then strip leading zeros for flexible matching @@ -387,7 +403,7 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) { } // Calculate next decimal using existing logic - const phasesDir = path.join(cwd, '.planning', 'phases'); + const phasesDir = path.join(planningDir(cwd), 'phases'); const normalizedBase = normalizePhaseName(afterPhase); let existingDecimals = []; @@ -399,12 +415,12 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) { const dm = dir.match(decimalPattern); if (dm) existingDecimals.push(parseInt(dm[1], 10)); } - } catch {} + } catch { /* intentionally empty */ } const nextDecimal = existingDecimals.length === 0 ? 1 : Math.max(...existingDecimals) + 1; const decimalPhase = `${normalizedBase}.${nextDecimal}`; const dirName = `${decimalPhase}-${slug}`; - const dirPath = path.join(cwd, '.planning', 'phases', dirName); + const dirPath = path.join(planningDir(cwd), 'phases', dirName); // Create directory with .gitkeep so git tracks empty folders fs.mkdirSync(dirPath, { recursive: true }); @@ -415,23 +431,23 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) { // Insert after the target phase section const headerPattern = new RegExp(`(#{2,4}\\s*Phase\\s+0*${afterPhaseEscaped}:[^\\n]*\\n)`, 'i'); - const headerMatch = content.match(headerPattern); + const headerMatch = rawContent.match(headerPattern); if (!headerMatch) { error(`Could not find Phase ${afterPhase} header`); } - const headerIdx = content.indexOf(headerMatch[0]); - const afterHeader = content.slice(headerIdx + headerMatch[0].length); + const headerIdx = rawContent.indexOf(headerMatch[0]); + const afterHeader = rawContent.slice(headerIdx + headerMatch[0].length); const nextPhaseMatch = afterHeader.match(/\n#{2,4}\s+Phase\s+\d/i); let insertIdx; if (nextPhaseMatch) { insertIdx = headerIdx + headerMatch[0].length + nextPhaseMatch.index; } else { - insertIdx = content.length; + insertIdx = rawContent.length; } - const updatedContent = content.slice(0, insertIdx) + phaseEntry + content.slice(insertIdx); + const updatedContent = rawContent.slice(0, insertIdx) + phaseEntry + rawContent.slice(insertIdx); fs.writeFileSync(roadmapPath, updatedContent, 'utf-8'); const result = { @@ -439,263 +455,175 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) { after_phase: afterPhase, name: description, slug, - directory: `.planning/phases/${dirName}`, + directory: toPosixPath(path.join(path.relative(cwd, planningDir(cwd)), 'phases', dirName)), }; output(result, raw, decimalPhase); } -function cmdPhaseRemove(cwd, targetPhase, options, raw) { - if (!targetPhase) { - error('phase number required for phase remove'); +/** + * Renumber sibling decimal phases after a decimal phase is removed. + * e.g. removing 06.2 → 06.3 becomes 06.2, 06.4 becomes 06.3, etc. + * Returns { renamedDirs, renamedFiles }. + */ +function renameDecimalPhases(phasesDir, baseInt, removedDecimal) { + const renamedDirs = [], renamedFiles = []; + const decPattern = new RegExp(`^${baseInt}\\.(\\d+)-(.+)$`); + const dirs = readSubdirectories(phasesDir, true); + const toRename = dirs + .map(dir => { const m = dir.match(decPattern); return m ? { dir, oldDecimal: parseInt(m[1], 10), slug: m[2] } : null; }) + .filter(item => item && item.oldDecimal > removedDecimal) + .sort((a, b) => b.oldDecimal - a.oldDecimal); // descending to avoid conflicts + + for (const item of toRename) { + const newDecimal = item.oldDecimal - 1; + const oldPhaseId = `${baseInt}.${item.oldDecimal}`; + const newPhaseId = `${baseInt}.${newDecimal}`; + const newDirName = `${baseInt}.${newDecimal}-${item.slug}`; + fs.renameSync(path.join(phasesDir, item.dir), path.join(phasesDir, newDirName)); + renamedDirs.push({ from: item.dir, to: newDirName }); + for (const f of fs.readdirSync(path.join(phasesDir, newDirName))) { + if (f.includes(oldPhaseId)) { + const newFileName = f.replace(oldPhaseId, newPhaseId); + fs.renameSync(path.join(phasesDir, newDirName, f), path.join(phasesDir, newDirName, newFileName)); + renamedFiles.push({ from: f, to: newFileName }); + } + } } + return { renamedDirs, renamedFiles }; +} - const roadmapPath = path.join(cwd, '.planning', 'ROADMAP.md'); - const phasesDir = path.join(cwd, '.planning', 'phases'); - const force = options.force || false; - - if (!fs.existsSync(roadmapPath)) { - error('ROADMAP.md not found'); +/** + * Renumber all integer phases after removedInt. + * e.g. removing phase 5 → phase 6 becomes 5, phase 7 becomes 6, etc. + * Returns { renamedDirs, renamedFiles }. + */ +function renameIntegerPhases(phasesDir, removedInt) { + const renamedDirs = [], renamedFiles = []; + const dirs = readSubdirectories(phasesDir, true); + const toRename = dirs + .map(dir => { + const m = dir.match(/^(\d+)([A-Z])?(?:\.(\d+))?-(.+)$/i); + if (!m) return null; + const dirInt = parseInt(m[1], 10); + return dirInt > removedInt ? { dir, oldInt: dirInt, letter: m[2] ? m[2].toUpperCase() : '', decimal: m[3] ? parseInt(m[3], 10) : null, slug: m[4] } : null; + }) + .filter(Boolean) + .sort((a, b) => a.oldInt !== b.oldInt ? b.oldInt - a.oldInt : (b.decimal || 0) - (a.decimal || 0)); + + for (const item of toRename) { + const newInt = item.oldInt - 1; + const newPadded = String(newInt).padStart(2, '0'); + const oldPadded = String(item.oldInt).padStart(2, '0'); + const letterSuffix = item.letter || ''; + const decimalSuffix = item.decimal !== null ? `.${item.decimal}` : ''; + const oldPrefix = `${oldPadded}${letterSuffix}${decimalSuffix}`; + const newPrefix = `${newPadded}${letterSuffix}${decimalSuffix}`; + const newDirName = `${newPrefix}-${item.slug}`; + fs.renameSync(path.join(phasesDir, item.dir), path.join(phasesDir, newDirName)); + renamedDirs.push({ from: item.dir, to: newDirName }); + for (const f of fs.readdirSync(path.join(phasesDir, newDirName))) { + if (f.startsWith(oldPrefix)) { + const newFileName = newPrefix + f.slice(oldPrefix.length); + fs.renameSync(path.join(phasesDir, newDirName, f), path.join(phasesDir, newDirName, newFileName)); + renamedFiles.push({ from: f, to: newFileName }); + } + } } + return { renamedDirs, renamedFiles }; +} - // Normalize the target - const normalized = normalizePhaseName(targetPhase); - const isDecimal = targetPhase.includes('.'); +/** + * Remove a phase section from ROADMAP.md and renumber all subsequent integer phases. + */ +function updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, removedInt) { + let content = fs.readFileSync(roadmapPath, 'utf-8'); + const escaped = escapeRegex(targetPhase); - // Find and validate target directory - let targetDir = null; - try { - const entries = fs.readdirSync(phasesDir, { withFileTypes: true }); - const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort((a, b) => comparePhaseNum(a, b)); - targetDir = dirs.find(d => d.startsWith(normalized + '-') || d === normalized); - } catch {} + content = content.replace(new RegExp(`\\n?#{2,4}\\s*Phase\\s+${escaped}\\s*:[\\s\\S]*?(?=\\n#{2,4}\\s+Phase\\s+\\d|$)`, 'i'), ''); + content = content.replace(new RegExp(`\\n?-\\s*\\[[ x]\\]\\s*.*Phase\\s+${escaped}[:\\s][^\\n]*`, 'gi'), ''); + content = content.replace(new RegExp(`\\n?\\|\\s*${escaped}\\.?\\s[^|]*\\|[^\\n]*`, 'gi'), ''); - // Check for executed work (SUMMARY.md files) - if (targetDir && !force) { - const targetPath = path.join(phasesDir, targetDir); - const files = fs.readdirSync(targetPath); - const summaries = files.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md'); - if (summaries.length > 0) { - error(`Phase ${targetPhase} has ${summaries.length} executed plan(s). Use --force to remove anyway.`); + if (!isDecimal) { + const MAX_PHASE = 99; + for (let oldNum = MAX_PHASE; oldNum > removedInt; oldNum--) { + const newNum = oldNum - 1; + const oldStr = String(oldNum), newStr = String(newNum); + const oldPad = oldStr.padStart(2, '0'), newPad = newStr.padStart(2, '0'); + content = content.replace(new RegExp(`(#{2,4}\\s*Phase\\s+)${oldStr}(\\s*:)`, 'gi'), `$1${newStr}$2`); + content = content.replace(new RegExp(`(Phase\\s+)${oldStr}([:\\s])`, 'g'), `$1${newStr}$2`); + content = content.replace(new RegExp(`${oldPad}-(\\d{2})`, 'g'), `${newPad}-$1`); + content = content.replace(new RegExp(`(\\|\\s*)${oldStr}\\.\\s`, 'g'), `$1${newStr}. `); + content = content.replace(new RegExp(`(Depends on:\\*\\*\\s*Phase\\s+)${oldStr}\\b`, 'gi'), `$1${newStr}`); } } - // Delete target directory - if (targetDir) { - fs.rmSync(path.join(phasesDir, targetDir), { recursive: true, force: true }); - } - - // Renumber subsequent phases - const renamedDirs = []; - const renamedFiles = []; - - if (isDecimal) { - // Decimal removal: renumber sibling decimals (e.g., removing 06.2 → 06.3 becomes 06.2) - const baseParts = normalized.split('.'); - const baseInt = baseParts[0]; - const removedDecimal = parseInt(baseParts[1], 10); - - try { - const entries = fs.readdirSync(phasesDir, { withFileTypes: true }); - const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort((a, b) => comparePhaseNum(a, b)); + fs.writeFileSync(roadmapPath, content, 'utf-8'); +} - // Find sibling decimals with higher numbers - const decPattern = new RegExp(`^${baseInt}\\.(\\d+)-(.+)$`); - const toRename = []; - for (const dir of dirs) { - const dm = dir.match(decPattern); - if (dm && parseInt(dm[1], 10) > removedDecimal) { - toRename.push({ dir, oldDecimal: parseInt(dm[1], 10), slug: dm[2] }); - } - } +function cmdPhaseRemove(cwd, targetPhase, options, raw) { + if (!targetPhase) error('phase number required for phase remove'); - // Sort descending to avoid conflicts - toRename.sort((a, b) => b.oldDecimal - a.oldDecimal); - - for (const item of toRename) { - const newDecimal = item.oldDecimal - 1; - const oldPhaseId = `${baseInt}.${item.oldDecimal}`; - const newPhaseId = `${baseInt}.${newDecimal}`; - const newDirName = `${baseInt}.${newDecimal}-${item.slug}`; - - // Rename directory - fs.renameSync(path.join(phasesDir, item.dir), path.join(phasesDir, newDirName)); - renamedDirs.push({ from: item.dir, to: newDirName }); - - // Rename files inside - const dirFiles = fs.readdirSync(path.join(phasesDir, newDirName)); - for (const f of dirFiles) { - // Files may have phase prefix like "06.2-01-PLAN.md" - if (f.includes(oldPhaseId)) { - const newFileName = f.replace(oldPhaseId, newPhaseId); - fs.renameSync( - path.join(phasesDir, newDirName, f), - path.join(phasesDir, newDirName, newFileName) - ); - renamedFiles.push({ from: f, to: newFileName }); - } - } - } - } catch {} + const roadmapPath = path.join(planningDir(cwd), 'ROADMAP.md'); + const phasesDir = path.join(planningDir(cwd), 'phases'); - } else { - // Integer removal: renumber all subsequent integer phases - const removedInt = parseInt(normalized, 10); + if (!fs.existsSync(roadmapPath)) error('ROADMAP.md not found'); - try { - const entries = fs.readdirSync(phasesDir, { withFileTypes: true }); - const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort((a, b) => comparePhaseNum(a, b)); + const normalized = normalizePhaseName(targetPhase); + const isDecimal = targetPhase.includes('.'); + const force = options.force || false; - // Collect directories that need renumbering (integer phases > removed, and their decimals/letters) - const toRename = []; - for (const dir of dirs) { - const dm = dir.match(/^(\d+)([A-Z])?(?:\.(\d+))?-(.+)$/i); - if (!dm) continue; - const dirInt = parseInt(dm[1], 10); - if (dirInt > removedInt) { - toRename.push({ - dir, - oldInt: dirInt, - letter: dm[2] ? dm[2].toUpperCase() : '', - decimal: dm[3] ? parseInt(dm[3], 10) : null, - slug: dm[4], - }); - } - } + // Find target directory + const targetDir = readSubdirectories(phasesDir, true) + .find(d => d.startsWith(normalized + '-') || d === normalized) || null; - // Sort descending to avoid conflicts - toRename.sort((a, b) => { - if (a.oldInt !== b.oldInt) return b.oldInt - a.oldInt; - return (b.decimal || 0) - (a.decimal || 0); - }); - - for (const item of toRename) { - const newInt = item.oldInt - 1; - const newPadded = String(newInt).padStart(2, '0'); - const oldPadded = String(item.oldInt).padStart(2, '0'); - const letterSuffix = item.letter || ''; - const decimalSuffix = item.decimal !== null ? `.${item.decimal}` : ''; - const oldPrefix = `${oldPadded}${letterSuffix}${decimalSuffix}`; - const newPrefix = `${newPadded}${letterSuffix}${decimalSuffix}`; - const newDirName = `${newPrefix}-${item.slug}`; - - // Rename directory - fs.renameSync(path.join(phasesDir, item.dir), path.join(phasesDir, newDirName)); - renamedDirs.push({ from: item.dir, to: newDirName }); - - // Rename files inside - const dirFiles = fs.readdirSync(path.join(phasesDir, newDirName)); - for (const f of dirFiles) { - if (f.startsWith(oldPrefix)) { - const newFileName = newPrefix + f.slice(oldPrefix.length); - fs.renameSync( - path.join(phasesDir, newDirName, f), - path.join(phasesDir, newDirName, newFileName) - ); - renamedFiles.push({ from: f, to: newFileName }); - } - } - } - } catch {} + // Guard against removing executed work + if (targetDir && !force) { + const files = fs.readdirSync(path.join(phasesDir, targetDir)); + const summaries = files.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md'); + if (summaries.length > 0) { + error(`Phase ${targetPhase} has ${summaries.length} executed plan(s). Use --force to remove anyway.`); + } } - // Update ROADMAP.md - let roadmapContent = fs.readFileSync(roadmapPath, 'utf-8'); - - // Remove the target phase section - const targetEscaped = escapeRegex(targetPhase); - const sectionPattern = new RegExp( - `\\n?#{2,4}\\s*Phase\\s+${targetEscaped}\\s*:[\\s\\S]*?(?=\\n#{2,4}\\s+Phase\\s+\\d|$)`, - 'i' - ); - roadmapContent = roadmapContent.replace(sectionPattern, ''); - - // Remove from phase list (checkbox) - const checkboxPattern = new RegExp(`\\n?-\\s*\\[[ x]\\]\\s*.*Phase\\s+${targetEscaped}[:\\s][^\\n]*`, 'gi'); - roadmapContent = roadmapContent.replace(checkboxPattern, ''); - - // Remove from progress table - const tableRowPattern = new RegExp(`\\n?\\|\\s*${targetEscaped}\\.?\\s[^|]*\\|[^\\n]*`, 'gi'); - roadmapContent = roadmapContent.replace(tableRowPattern, ''); + if (targetDir) fs.rmSync(path.join(phasesDir, targetDir), { recursive: true, force: true }); - // Renumber references in ROADMAP for subsequent phases - if (!isDecimal) { - const removedInt = parseInt(normalized, 10); - - // Collect all integer phases > removedInt - const maxPhase = 99; // reasonable upper bound - for (let oldNum = maxPhase; oldNum > removedInt; oldNum--) { - const newNum = oldNum - 1; - const oldStr = String(oldNum); - const newStr = String(newNum); - const oldPad = oldStr.padStart(2, '0'); - const newPad = newStr.padStart(2, '0'); - - // Phase headings: ## Phase 18: or ### Phase 18: → ## Phase 17: or ### Phase 17: - roadmapContent = roadmapContent.replace( - new RegExp(`(#{2,4}\\s*Phase\\s+)${oldStr}(\\s*:)`, 'gi'), - `$1${newStr}$2` - ); - - // Checkbox items: - [ ] **Phase 18:** → - [ ] **Phase 17:** - roadmapContent = roadmapContent.replace( - new RegExp(`(Phase\\s+)${oldStr}([:\\s])`, 'g'), - `$1${newStr}$2` - ); - - // Plan references: 18-01 → 17-01 - roadmapContent = roadmapContent.replace( - new RegExp(`${oldPad}-(\\d{2})`, 'g'), - `${newPad}-$1` - ); - - // Table rows: | 18. → | 17. - roadmapContent = roadmapContent.replace( - new RegExp(`(\\|\\s*)${oldStr}\\.\\s`, 'g'), - `$1${newStr}. ` - ); - - // Depends on references - roadmapContent = roadmapContent.replace( - new RegExp(`(Depends on:\\*\\*\\s*Phase\\s+)${oldStr}\\b`, 'gi'), - `$1${newStr}` - ); - } - } + // Renumber subsequent phases on disk + let renamedDirs = [], renamedFiles = []; + try { + const renamed = isDecimal + ? renameDecimalPhases(phasesDir, normalized.split('.')[0], parseInt(normalized.split('.')[1], 10)) + : renameIntegerPhases(phasesDir, parseInt(normalized, 10)); + renamedDirs = renamed.renamedDirs; + renamedFiles = renamed.renamedFiles; + } catch { /* intentionally empty */ } - fs.writeFileSync(roadmapPath, roadmapContent, 'utf-8'); + // Update ROADMAP.md + updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, parseInt(normalized, 10)); // Update STATE.md phase count - const statePath = path.join(cwd, '.planning', 'STATE.md'); + const statePath = path.join(planningDir(cwd), 'STATE.md'); if (fs.existsSync(statePath)) { let stateContent = fs.readFileSync(statePath, 'utf-8'); - // Update "Total Phases" field - const totalPattern = /(\*\*Total Phases:\*\*\s*)(\d+)/; - const totalMatch = stateContent.match(totalPattern); - if (totalMatch) { - const oldTotal = parseInt(totalMatch[2], 10); - stateContent = stateContent.replace(totalPattern, `$1${oldTotal - 1}`); + const totalRaw = stateExtractField(stateContent, 'Total Phases'); + if (totalRaw) { + stateContent = stateReplaceField(stateContent, 'Total Phases', String(parseInt(totalRaw, 10) - 1)) || stateContent; } - // Update "Phase: X of Y" pattern - const ofPattern = /(\bof\s+)(\d+)(\s*(?:\(|phases?))/i; - const ofMatch = stateContent.match(ofPattern); + const ofMatch = stateContent.match(/(\bof\s+)(\d+)(\s*(?:\(|phases?))/i); if (ofMatch) { - const oldTotal = parseInt(ofMatch[2], 10); - stateContent = stateContent.replace(ofPattern, `$1${oldTotal - 1}$3`); + stateContent = stateContent.replace(/(\bof\s+)(\d+)(\s*(?:\(|phases?))/i, `$1${parseInt(ofMatch[2], 10) - 1}$3`); } writeStateMd(statePath, stateContent, cwd); } - const result = { + output({ removed: targetPhase, - directory_deleted: targetDir || null, + directory_deleted: targetDir, renamed_directories: renamedDirs, renamed_files: renamedFiles, roadmap_updated: true, state_updated: fs.existsSync(statePath), - }; - - output(result, raw); + }, raw); } function cmdPhaseComplete(cwd, phaseNum, raw) { @@ -703,9 +631,9 @@ function cmdPhaseComplete(cwd, phaseNum, raw) { error('phase number required for phase complete'); } - const roadmapPath = path.join(cwd, '.planning', 'ROADMAP.md'); - const statePath = path.join(cwd, '.planning', 'STATE.md'); - const phasesDir = path.join(cwd, '.planning', 'phases'); + const roadmapPath = path.join(planningDir(cwd), 'ROADMAP.md'); + const statePath = path.join(planningDir(cwd), 'STATE.md'); + const phasesDir = path.join(planningDir(cwd), 'phases'); const normalized = normalizePhaseName(phaseNum); const today = new Date().toISOString().split('T')[0]; @@ -717,6 +645,28 @@ function cmdPhaseComplete(cwd, phaseNum, raw) { const planCount = phaseInfo.plans.length; const summaryCount = phaseInfo.summaries.length; + let requirementsUpdated = false; + + // Check for unresolved verification debt (non-blocking warnings) + const warnings = []; + try { + const phaseFullDir = path.join(cwd, phaseInfo.directory); + const phaseFiles = fs.readdirSync(phaseFullDir); + + for (const file of phaseFiles.filter(f => f.includes('-UAT') && f.endsWith('.md'))) { + const content = fs.readFileSync(path.join(phaseFullDir, file), 'utf-8'); + if (/result: pending/.test(content)) warnings.push(`${file}: has pending tests`); + if (/result: blocked/.test(content)) warnings.push(`${file}: has blocked tests`); + if (/status: partial/.test(content)) warnings.push(`${file}: testing incomplete (partial)`); + if (/status: diagnosed/.test(content)) warnings.push(`${file}: has diagnosed gaps`); + } + + for (const file of phaseFiles.filter(f => f.includes('-VERIFICATION') && f.endsWith('.md'))) { + const content = fs.readFileSync(path.join(phaseFullDir, file), 'utf-8'); + if (/status: human_needed/.test(content)) warnings.push(`${file}: needs human verification`); + if (/status: gaps_found/.test(content)) warnings.push(`${file}: has unresolved gaps`); + } + } catch {} // Update ROADMAP.md: mark phase complete if (fs.existsSync(roadmapPath)) { @@ -727,39 +677,53 @@ function cmdPhaseComplete(cwd, phaseNum, raw) { `(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${escapeRegex(phaseNum)}[:\\s][^\\n]*)`, 'i' ); - roadmapContent = roadmapContent.replace(checkboxPattern, `$1x$2 (completed ${today})`); + roadmapContent = replaceInCurrentMilestone(roadmapContent, checkboxPattern, `$1x$2 (completed ${today})`); - // Progress table: update Status to Complete, add date + // Progress table: update Status to Complete, add date (handles 4 or 5 column tables) const phaseEscaped = escapeRegex(phaseNum); - const tablePattern = new RegExp( - `(\\|\\s*${phaseEscaped}\\.?\\s[^|]*\\|[^|]*\\|)\\s*[^|]*(\\|)\\s*[^|]*(\\|)`, - 'i' - ); - roadmapContent = roadmapContent.replace( - tablePattern, - `$1 Complete $2 ${today} $3` + const tableRowPattern = new RegExp( + `^(\\|\\s*${phaseEscaped}\\.?\\s[^|]*(?:\\|[^\\n]*))$`, + 'im' ); + roadmapContent = roadmapContent.replace(tableRowPattern, (fullRow) => { + const cells = fullRow.split('|').slice(1, -1); + if (cells.length === 5) { + // 5-col: Phase | Milestone | Plans | Status | Completed + cells[3] = ' Complete '; + cells[4] = ` ${today} `; + } else if (cells.length === 4) { + // 4-col: Phase | Plans | Status | Completed + cells[2] = ' Complete '; + cells[3] = ` ${today} `; + } + return '|' + cells.join('|') + '|'; + }); // Update plan count in phase section const planCountPattern = new RegExp( `(#{2,4}\\s*Phase\\s+${phaseEscaped}[\\s\\S]*?\\*\\*Plans:\\*\\*\\s*)[^\\n]+`, 'i' ); - roadmapContent = roadmapContent.replace( - planCountPattern, + roadmapContent = replaceInCurrentMilestone( + roadmapContent, planCountPattern, `$1${summaryCount}/${planCount} plans complete` ); fs.writeFileSync(roadmapPath, roadmapContent, 'utf-8'); // Update REQUIREMENTS.md traceability for this phase's requirements - const reqPath = path.join(cwd, '.planning', 'REQUIREMENTS.md'); + const reqPath = path.join(planningDir(cwd), 'REQUIREMENTS.md'); if (fs.existsSync(reqPath)) { - // Extract Requirements line from roadmap for this phase - const reqMatch = roadmapContent.match( - new RegExp(`Phase\\s+${escapeRegex(phaseNum)}[\\s\\S]*?\\*\\*Requirements:\\*\\*\\s*([^\\n]+)`, 'i') + // Extract the current phase section from roadmap (scoped to avoid cross-phase matching) + const phaseEsc = escapeRegex(phaseNum); + const currentMilestoneRoadmap = extractCurrentMilestone(roadmapContent, cwd); + const phaseSectionMatch = currentMilestoneRoadmap.match( + new RegExp(`(#{2,4}\\s*Phase\\s+${phaseEsc}[:\\s][\\s\\S]*?)(?=#{2,4}\\s*Phase\\s+|$)`, 'i') ); + const sectionText = phaseSectionMatch ? phaseSectionMatch[1] : ''; + const reqMatch = sectionText.match(/\*\*Requirements:\*\*\s*([^\n]+)/i); + if (reqMatch) { const reqIds = reqMatch[1].replace(/[\[\]]/g, '').split(/[,\s]+/).map(r => r.trim()).filter(Boolean); let reqContent = fs.readFileSync(reqPath, 'utf-8'); @@ -771,14 +735,15 @@ function cmdPhaseComplete(cwd, phaseNum, raw) { new RegExp(`(-\\s*\\[)[ ](\\]\\s*\\*\\*${reqEscaped}\\*\\*)`, 'gi'), '$1x$2' ); - // Update traceability table: | REQ-ID | Phase N | Pending | → | REQ-ID | Phase N | Complete | + // Update traceability table: | REQ-ID | Phase N | Pending/In Progress | → | REQ-ID | Phase N | Complete | reqContent = reqContent.replace( - new RegExp(`(\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|)\\s*Pending\\s*(\\|)`, 'gi'), + new RegExp(`(\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|)\\s*(?:Pending|In Progress)\\s*(\\|)`, 'gi'), '$1 Complete $2' ); } fs.writeFileSync(reqPath, reqContent, 'utf-8'); + requirementsUpdated = true; } } } @@ -809,13 +774,13 @@ function cmdPhaseComplete(cwd, phaseNum, raw) { } } } - } catch {} + } catch { /* intentionally empty */ } // Fallback: if filesystem found no next phase, check ROADMAP.md // for phases that are defined but not yet planned (no directory on disk) if (isLastPhase && fs.existsSync(roadmapPath)) { try { - const roadmapForPhases = fs.readFileSync(roadmapPath, 'utf-8'); + const roadmapForPhases = extractCurrentMilestone(fs.readFileSync(roadmapPath, 'utf-8'), cwd); const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:\s*([^\n]+)/gi; let pm; while ((pm = phasePattern.exec(roadmapForPhases)) !== null) { @@ -826,50 +791,69 @@ function cmdPhaseComplete(cwd, phaseNum, raw) { break; } } - } catch {} + } catch { /* intentionally empty */ } } - // Update STATE.md + // Update STATE.md — use shared helpers that handle both **bold:** and plain Field: formats if (fs.existsSync(statePath)) { let stateContent = fs.readFileSync(statePath, 'utf-8'); - // Update Current Phase - stateContent = stateContent.replace( - /(\*\*Current Phase:\*\*\s*).*/, - `$1${nextPhaseNum || phaseNum}` - ); + // Update Current Phase — preserve "X of Y (Name)" compound format + const phaseValue = nextPhaseNum || phaseNum; + const existingPhaseField = stateExtractField(stateContent, 'Current Phase') + || stateExtractField(stateContent, 'Phase'); + let newPhaseValue = String(phaseValue); + if (existingPhaseField) { + const totalMatch = existingPhaseField.match(/of\s+(\d+)/); + const nameMatch = existingPhaseField.match(/\(([^)]+)\)/); + if (totalMatch) { + const total = totalMatch[1]; + const nameStr = nextPhaseName ? ` (${nextPhaseName.replace(/-/g, ' ')})` : (nameMatch ? ` (${nameMatch[1]})` : ''); + newPhaseValue = `${phaseValue} of ${total}${nameStr}`; + } + } + stateContent = stateReplaceFieldWithFallback(stateContent, 'Current Phase', 'Phase', newPhaseValue); // Update Current Phase Name if (nextPhaseName) { - stateContent = stateContent.replace( - /(\*\*Current Phase Name:\*\*\s*).*/, - `$1${nextPhaseName.replace(/-/g, ' ')}` - ); + stateContent = stateReplaceFieldWithFallback(stateContent, 'Current Phase Name', null, nextPhaseName.replace(/-/g, ' ')); } // Update Status - stateContent = stateContent.replace( - /(\*\*Status:\*\*\s*).*/, - `$1${isLastPhase ? 'Milestone complete' : 'Ready to plan'}` - ); + stateContent = stateReplaceFieldWithFallback(stateContent, 'Status', null, + isLastPhase ? 'Milestone complete' : 'Ready to plan'); // Update Current Plan - stateContent = stateContent.replace( - /(\*\*Current Plan:\*\*\s*).*/, - `$1Not started` - ); + stateContent = stateReplaceFieldWithFallback(stateContent, 'Current Plan', 'Plan', 'Not started'); // Update Last Activity - stateContent = stateContent.replace( - /(\*\*Last Activity:\*\*\s*).*/, - `$1${today}` - ); + stateContent = stateReplaceFieldWithFallback(stateContent, 'Last Activity', 'Last activity', today); // Update Last Activity Description - stateContent = stateContent.replace( - /(\*\*Last Activity Description:\*\*\s*).*/, - `$1Phase ${phaseNum} complete${nextPhaseNum ? `, transitioned to Phase ${nextPhaseNum}` : ''}` - ); + stateContent = stateReplaceFieldWithFallback(stateContent, 'Last Activity Description', null, + `Phase ${phaseNum} complete${nextPhaseNum ? `, transitioned to Phase ${nextPhaseNum}` : ''}`); + + // Increment Completed Phases counter (#956) + const completedRaw = stateExtractField(stateContent, 'Completed Phases'); + if (completedRaw) { + const newCompleted = parseInt(completedRaw, 10) + 1; + stateContent = stateReplaceField(stateContent, 'Completed Phases', String(newCompleted)) || stateContent; + + // Recalculate percent based on completed / total (#956) + const totalRaw = stateExtractField(stateContent, 'Total Phases'); + if (totalRaw) { + const totalPhases = parseInt(totalRaw, 10); + if (totalPhases > 0) { + const newPercent = Math.round((newCompleted / totalPhases) * 100); + stateContent = stateReplaceField(stateContent, 'Progress', `${newPercent}%`) || stateContent; + // Also update percent field if it exists separately + stateContent = stateContent.replace( + /(percent:\s*)\d+/, + `$1${newPercent}` + ); + } + } + } writeStateMd(statePath, stateContent, cwd); } @@ -884,6 +868,9 @@ function cmdPhaseComplete(cwd, phaseNum, raw) { date: today, roadmap_updated: fs.existsSync(roadmapPath), state_updated: fs.existsSync(statePath), + requirements_updated: requirementsUpdated, + warnings, + has_warnings: warnings.length > 0, }; output(result, raw); diff --git a/gsd-opencode/get-shit-done/bin/lib/profile-output.cjs b/gsd-opencode/get-shit-done/bin/lib/profile-output.cjs new file mode 100644 index 0000000..212a287 --- /dev/null +++ b/gsd-opencode/get-shit-done/bin/lib/profile-output.cjs @@ -0,0 +1,952 @@ +/** + * Profile Output — profile rendering, questionnaire, and artifact generation + * + * Renders profiling analysis into user-facing artifacts: + * - write-profile: USER-PROFILE.md from analysis JSON + * - profile-questionnaire: fallback when no sessions available + * - generate-dev-preferences: dev-preferences.md command artifact + * - generate-OpenCode-profile: Developer Profile section in AGENTS.md + * - generate-OpenCode-md: full AGENTS.md with managed sections + */ + +const fs = require('fs'); +const path = require('path'); +const os = require('os'); +const { output, error, safeReadFile } = require('./core.cjs'); + +// ─── Constants ──────────────────────────────────────────────────────────────── + +const DIMENSION_KEYS = [ + 'communication_style', 'decision_speed', 'explanation_depth', + 'debugging_approach', 'ux_philosophy', 'vendor_philosophy', + 'frustration_triggers', 'learning_style' +]; + +const PROFILING_QUESTIONS = [ + { + dimension: 'communication_style', + header: 'Communication Style', + context: 'Think about the last few times you asked OpenCode to build or change something. How did you frame the request?', + question: 'When you ask OpenCode to build something, how much context do you typically provide?', + options: [ + { label: 'Minimal -- "fix the bug", "add dark mode", just say what\'s needed', value: 'a', rating: 'terse-direct' }, + { label: 'Some context -- explain what and why in a paragraph or two', value: 'b', rating: 'conversational' }, + { label: 'Detailed specs -- headers, numbered lists, problem analysis, constraints', value: 'c', rating: 'detailed-structured' }, + { label: 'It depends on the task -- simple tasks get short prompts, complex ones get detailed specs', value: 'd', rating: 'mixed' }, + ], + }, + { + dimension: 'decision_speed', + header: 'Decision Making', + context: 'Think about times when OpenCode presented you with multiple options -- like choosing a library, picking an architecture, or selecting an approach.', + question: 'When OpenCode presents you with options, how do you typically decide?', + options: [ + { label: 'Pick quickly based on gut feeling or past experience', value: 'a', rating: 'fast-intuitive' }, + { label: 'Ask for a comparison table or pros/cons, then decide', value: 'b', rating: 'deliberate-informed' }, + { label: 'Research independently (read docs, check GitHub stars) before deciding', value: 'c', rating: 'research-first' }, + { label: 'Let OpenCode recommend -- I generally trust the suggestion', value: 'd', rating: 'delegator' }, + ], + }, + { + dimension: 'explanation_depth', + header: 'Explanation Preferences', + context: 'Think about when OpenCode explains code it wrote or an approach it took. How much detail feels right?', + question: 'When OpenCode explains something, how much detail do you want?', + options: [ + { label: 'Just the code -- I\'ll read it and figure it out myself', value: 'a', rating: 'code-only' }, + { label: 'Brief explanation with the code -- a sentence or two about the approach', value: 'b', rating: 'concise' }, + { label: 'Detailed walkthrough -- explain the approach, trade-offs, and code structure', value: 'c', rating: 'detailed' }, + { label: 'Deep dive -- teach me the concepts behind it so I understand the fundamentals', value: 'd', rating: 'educational' }, + ], + }, + { + dimension: 'debugging_approach', + header: 'Debugging Style', + context: 'Think about the last few times something broke in your code. How did you approach it with OpenCode?', + question: 'When something breaks, how do you typically approach debugging with OpenCode?', + options: [ + { label: 'Paste the error and say "fix it" -- get it working fast', value: 'a', rating: 'fix-first' }, + { label: 'Share the error plus context, ask OpenCode to diagnose what went wrong', value: 'b', rating: 'diagnostic' }, + { label: 'Investigate myself first, then ask OpenCode about my specific theories', value: 'c', rating: 'hypothesis-driven' }, + { label: 'Walk through the code together step by step to understand the issue', value: 'd', rating: 'collaborative' }, + ], + }, + { + dimension: 'ux_philosophy', + header: 'UX Philosophy', + context: 'Think about user-facing features you have built recently. How did you balance functionality with design?', + question: 'When building user-facing features, what do you prioritize?', + options: [ + { label: 'Get it working first, polish the UI later (or never)', value: 'a', rating: 'function-first' }, + { label: 'Basic usability from the start -- nothing ugly, but no pixel-perfection', value: 'b', rating: 'pragmatic' }, + { label: 'Design and UX are as important as functionality -- I care about the experience', value: 'c', rating: 'design-conscious' }, + { label: 'I mostly build backend, CLI, or infrastructure -- UX is minimal', value: 'd', rating: 'backend-focused' }, + ], + }, + { + dimension: 'vendor_philosophy', + header: 'Library & Vendor Choices', + context: 'Think about the last time you needed a library or service for a project. How did you go about choosing it?', + question: 'When choosing libraries or services, what is your typical approach?', + options: [ + { label: 'Use whatever OpenCode suggests -- speed matters more than the perfect choice', value: 'a', rating: 'pragmatic-fast' }, + { label: 'Prefer well-known, battle-tested options (React, PostgreSQL, Express)', value: 'b', rating: 'conservative' }, + { label: 'Research alternatives, read docs, compare benchmarks before committing', value: 'c', rating: 'thorough-evaluator' }, + { label: 'Strong opinions -- I already know what I like and I stick with it', value: 'd', rating: 'opinionated' }, + ], + }, + { + dimension: 'frustration_triggers', + header: 'Frustration Triggers', + context: 'Think about moments when working with AI coding assistants that made you frustrated or annoyed.', + question: 'What frustrates you most when working with AI coding assistants?', + options: [ + { label: 'Doing things I didn\'t ask for -- adding features, refactoring code, scope creep', value: 'a', rating: 'scope-creep' }, + { label: 'Not following instructions precisely -- ignoring constraints or requirements I stated', value: 'b', rating: 'instruction-adherence' }, + { label: 'Over-explaining or being too verbose -- just give me the code and move on', value: 'c', rating: 'verbosity' }, + { label: 'Breaking working code while fixing something else -- regressions', value: 'd', rating: 'regression' }, + ], + }, + { + dimension: 'learning_style', + header: 'Learning Preferences', + context: 'Think about encountering something new -- an unfamiliar library, a codebase you inherited, a concept you hadn\'t used before.', + question: 'When you encounter something new in your codebase, how do you prefer to learn about it?', + options: [ + { label: 'read the code directly -- I figure things out by reading and experimenting', value: 'a', rating: 'self-directed' }, + { label: 'Ask OpenCode to explain the relevant parts to me', value: 'b', rating: 'guided' }, + { label: 'read official docs and tutorials first, then try things', value: 'c', rating: 'documentation-first' }, + { label: 'See a working example, then modify it to understand how it works', value: 'd', rating: 'example-driven' }, + ], + }, +]; + +const CLAUDE_INSTRUCTIONS = { + communication_style: { + 'terse-direct': 'Keep responses concise and action-oriented. Skip lengthy preambles. Match this developer\'s direct style.', + 'conversational': 'Use a natural conversational tone. Explain reasoning briefly alongside code. Engage with the developer\'s questions.', + 'detailed-structured': 'Match this developer\'s structured communication: use headers for sections, numbered lists for steps, and acknowledge provided context before responding.', + 'mixed': 'Adapt response detail to match the complexity of each request. Brief for simple tasks, detailed for complex ones.', + }, + decision_speed: { + 'fast-intuitive': 'Present a single strong recommendation with brief justification. Skip lengthy comparisons unless asked.', + 'deliberate-informed': 'Present options in a structured comparison table with pros/cons. Let the developer make the final call.', + 'research-first': 'Include links to docs, GitHub repos, or benchmarks when recommending tools. Support the developer\'s research process.', + 'delegator': 'Make clear recommendations with confidence. Explain your reasoning briefly, but own the suggestion.', + }, + explanation_depth: { + 'code-only': 'Prioritize code output. Add comments inline rather than prose explanations. Skip walkthroughs unless asked.', + 'concise': 'Pair code with a brief explanation (1-2 sentences) of the approach. Keep prose minimal.', + 'detailed': 'Explain the approach, key trade-offs, and code structure alongside the implementation. Use headers to organize.', + 'educational': 'Teach the underlying concepts and principles, not just the implementation. Relate new patterns to fundamentals.', + }, + debugging_approach: { + 'fix-first': 'Prioritize the fix. Show the corrected code first, then optionally explain what was wrong. Minimize diagnostic preamble.', + 'diagnostic': 'Diagnose the root cause before presenting the fix. Explain what went wrong and why the fix addresses it.', + 'hypothesis-driven': 'Engage with the developer\'s theories. Validate or refine their hypotheses before jumping to solutions.', + 'collaborative': 'Walk through the debugging process step by step. Explain the investigation approach, not just the conclusion.', + }, + ux_philosophy: { + 'function-first': 'Focus on functionality and correctness. Keep UI minimal and functional. Skip design polish unless requested.', + 'pragmatic': 'Build clean, usable interfaces without over-engineering. Apply basic design principles (spacing, alignment, contrast).', + 'design-conscious': 'Invest in UX quality: thoughtful spacing, smooth transitions, responsive layouts. Treat design as a first-class concern.', + 'backend-focused': 'Optimize for developer experience (clear APIs, good error messages, helpful CLI output) over visual design.', + }, + vendor_philosophy: { + 'pragmatic-fast': 'Suggest libraries quickly based on popularity and reliability. Don\'t over-analyze choices for non-critical dependencies.', + 'conservative': 'Recommend well-established, widely-adopted tools with strong community support. Avoid bleeding-edge options.', + 'thorough-evaluator': 'Compare alternatives with specific metrics (bundle size, GitHub stars, maintenance activity). Support informed decisions.', + 'opinionated': 'Respect the developer\'s existing tool preferences. Ask before suggesting alternatives to their preferred stack.', + }, + frustration_triggers: { + 'scope-creep': 'Do exactly what is asked -- nothing more. Never add unrequested features, refactoring, or "improvements". Ask before expanding scope.', + 'instruction-adherence': 'Follow instructions precisely. Re-read constraints before responding. If requirements conflict, flag the conflict rather than silently choosing.', + 'verbosity': 'Be concise. Lead with code, follow with brief explanation only if needed. Avoid restating the problem or unnecessary context.', + 'regression': 'Before modifying working code, verify the change is safe. Run existing tests mentally. Flag potential regression risks explicitly.', + }, + learning_style: { + 'self-directed': 'Point to relevant code sections and let the developer explore. Add signposts (file paths, function names) rather than full explanations.', + 'guided': 'Explain concepts in context of the developer\'s codebase. Use their actual code as examples when teaching.', + 'documentation-first': 'Link to official documentation and relevant sections. Structure explanations like reference material.', + 'example-driven': 'Lead with working code examples. Show a minimal example first, then explain how to extend or modify it.', + }, +}; + +const CLAUDE_MD_FALLBACKS = { + project: 'Project not yet initialized. Run /gsd-new-project to set up.', + stack: 'Technology stack not yet documented. Will populate after codebase mapping or first phase.', + conventions: 'Conventions not yet established. Will populate as patterns emerge during development.', + architecture: 'Architecture not yet mapped. Follow existing patterns found in the codebase.', +}; + +const CLAUDE_MD_WORKFLOW_ENFORCEMENT = [ + 'Before using edit, write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync.', + '', + 'Use these entry points:', + '- `/gsd-quick` for small fixes, doc updates, and ad-hoc tasks', + '- `/gsd-debug` for investigation and bug fixing', + '- `/gsd-execute-phase` for planned phase work', + '', + 'Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it.', +].join('\n'); + +const CLAUDE_MD_PROFILE_PLACEHOLDER = [ + '', + '## Developer Profile', + '', + '> Profile not yet configured. Run `/gsd-profile-user` to generate your developer profile.', + '> This section is managed by `generate-OpenCode-profile` -- do not edit manually.', + '', +].join('\n'); + +// ─── Helper Functions ───────────────────────────────────────────────────────── + +function isAmbiguousAnswer(dimension, value) { + if (dimension === 'communication_style' && value === 'd') return true; + const question = PROFILING_QUESTIONS.find(q => q.dimension === dimension); + if (!question) return false; + const option = question.options.find(o => o.value === value); + if (!option) return false; + return option.rating === 'mixed'; +} + +function generateClaudeInstruction(dimension, rating) { + const dimInstructions = CLAUDE_INSTRUCTIONS[dimension]; + if (dimInstructions && dimInstructions[rating]) { + return dimInstructions[rating]; + } + return `Adapt to this developer's ${dimension.replace(/_/g, ' ')} preference: ${rating}.`; +} + +function extractSectionContent(fileContent, sectionName) { + const startMarker = ``; + const startIdx = fileContent.indexOf(startMarker); + const endIdx = fileContent.indexOf(endMarker); + if (startIdx === -1 || endIdx === -1) return null; + const startTagEnd = fileContent.indexOf('-->', startIdx); + if (startTagEnd === -1) return null; + return fileContent.substring(startTagEnd + 3, endIdx); +} + +function buildSection(sectionName, sourceFile, content) { + return [ + ``, + content, + ``, + ].join('\n'); +} + +function updateSection(fileContent, sectionName, newContent) { + const startMarker = ``; + const startIdx = fileContent.indexOf(startMarker); + const endIdx = fileContent.indexOf(endMarker); + if (startIdx !== -1 && endIdx !== -1) { + const before = fileContent.substring(0, startIdx); + const after = fileContent.substring(endIdx + endMarker.length); + return { content: before + newContent + after, action: 'replaced' }; + } + return { content: fileContent.trimEnd() + '\n\n' + newContent + '\n', action: 'appended' }; +} + +function detectManualEdit(fileContent, sectionName, expectedContent) { + const currentContent = extractSectionContent(fileContent, sectionName); + if (currentContent === null) return false; + const normalize = (s) => s.trim().replace(/\n{3,}/g, '\n\n'); + return normalize(currentContent) !== normalize(expectedContent); +} + +function extractMarkdownSection(content, sectionName) { + if (!content) return null; + const lines = content.split('\n'); + let capturing = false; + const result = []; + const headingPattern = new RegExp(`^## ${sectionName}\\s*$`); + for (const line of lines) { + if (headingPattern.test(line)) { + capturing = true; + result.push(line); + continue; + } + if (capturing && /^## /.test(line)) break; + if (capturing) result.push(line); + } + return result.length > 0 ? result.join('\n').trim() : null; +} + +// ─── AGENTS.md Section Generators ───────────────────────────────────────────── + +function generateProjectSection(cwd) { + const projectPath = path.join(cwd, '.planning', 'PROJECT.md'); + const content = safeReadFile(projectPath); + if (!content) { + return { content: CLAUDE_MD_FALLBACKS.project, source: 'PROJECT.md', hasFallback: true }; + } + const parts = []; + const h1Match = content.match(/^# (.+)$/m); + if (h1Match) parts.push(`**${h1Match[1]}**`); + const whatThisIs = extractMarkdownSection(content, 'What This Is'); + if (whatThisIs) { + const body = whatThisIs.replace(/^## What This Is\s*/i, '').trim(); + if (body) parts.push(body); + } + const coreValue = extractMarkdownSection(content, 'Core Value'); + if (coreValue) { + const body = coreValue.replace(/^## Core Value\s*/i, '').trim(); + if (body) parts.push(`**Core Value:** ${body}`); + } + const constraints = extractMarkdownSection(content, 'Constraints'); + if (constraints) { + const body = constraints.replace(/^## Constraints\s*/i, '').trim(); + if (body) parts.push(`### Constraints\n\n${body}`); + } + if (parts.length === 0) { + return { content: CLAUDE_MD_FALLBACKS.project, source: 'PROJECT.md', hasFallback: true }; + } + return { content: parts.join('\n\n'), source: 'PROJECT.md', hasFallback: false }; +} + +function generateStackSection(cwd) { + const codebasePath = path.join(cwd, '.planning', 'codebase', 'STACK.md'); + const researchPath = path.join(cwd, '.planning', 'research', 'STACK.md'); + let content = safeReadFile(codebasePath); + let source = 'codebase/STACK.md'; + if (!content) { + content = safeReadFile(researchPath); + source = 'research/STACK.md'; + } + if (!content) { + return { content: CLAUDE_MD_FALLBACKS.stack, source: 'STACK.md', hasFallback: true }; + } + const lines = content.split('\n'); + const summaryLines = []; + let inTable = false; + for (const line of lines) { + if (line.startsWith('#')) { + if (!line.startsWith('# ') || summaryLines.length > 0) summaryLines.push(line); + continue; + } + if (line.startsWith('|')) { inTable = true; summaryLines.push(line); continue; } + if (inTable && line.trim() === '') inTable = false; + if (line.startsWith('- ') || line.startsWith('* ')) summaryLines.push(line); + } + const summary = summaryLines.length > 0 ? summaryLines.join('\n') : content.trim(); + return { content: summary, source, hasFallback: false }; +} + +function generateConventionsSection(cwd) { + const conventionsPath = path.join(cwd, '.planning', 'codebase', 'CONVENTIONS.md'); + const content = safeReadFile(conventionsPath); + if (!content) { + return { content: CLAUDE_MD_FALLBACKS.conventions, source: 'CONVENTIONS.md', hasFallback: true }; + } + const lines = content.split('\n'); + const summaryLines = []; + for (const line of lines) { + if (line.startsWith('#')) { if (!line.startsWith('# ')) summaryLines.push(line); continue; } + if (line.startsWith('- ') || line.startsWith('* ') || line.startsWith('|')) summaryLines.push(line); + } + const summary = summaryLines.length > 0 ? summaryLines.join('\n') : content.trim(); + return { content: summary, source: 'CONVENTIONS.md', hasFallback: false }; +} + +function generateArchitectureSection(cwd) { + const architecturePath = path.join(cwd, '.planning', 'codebase', 'ARCHITECTURE.md'); + const content = safeReadFile(architecturePath); + if (!content) { + return { content: CLAUDE_MD_FALLBACKS.architecture, source: 'ARCHITECTURE.md', hasFallback: true }; + } + const lines = content.split('\n'); + const summaryLines = []; + for (const line of lines) { + if (line.startsWith('#')) { if (!line.startsWith('# ')) summaryLines.push(line); continue; } + if (line.startsWith('- ') || line.startsWith('* ') || line.startsWith('|') || line.startsWith('```')) summaryLines.push(line); + } + const summary = summaryLines.length > 0 ? summaryLines.join('\n') : content.trim(); + return { content: summary, source: 'ARCHITECTURE.md', hasFallback: false }; +} + +function generateWorkflowSection() { + return { + content: CLAUDE_MD_WORKFLOW_ENFORCEMENT, + source: 'GSD defaults', + hasFallback: false, + }; +} + +// ─── Commands ───────────────────────────────────────────────────────────────── + +function cmdWriteProfile(cwd, options, raw) { + if (!options.input) { + error('--input is required'); + } + + let analysisPath = options.input; + if (!path.isAbsolute(analysisPath)) analysisPath = path.join(cwd, analysisPath); + if (!fs.existsSync(analysisPath)) error(`Analysis file not found: ${analysisPath}`); + + let analysis; + try { + analysis = JSON.parse(fs.readFileSync(analysisPath, 'utf-8')); + } catch (err) { + error(`Failed to parse analysis JSON: ${err.message}`); + } + + if (!analysis.dimensions || typeof analysis.dimensions !== 'object') { + error('Analysis JSON must contain a "dimensions" object'); + } + if (!analysis.profile_version) { + error('Analysis JSON must contain "profile_version"'); + } + + const SENSITIVE_PATTERNS = [ + /sk-[a-zA-Z0-9]{20,}/g, + /Bearer\s+[a-zA-Z0-9._-]+/gi, + /password\s*[:=]\s*\S+/gi, + /secret\s*[:=]\s*\S+/gi, + /token\s*[:=]\s*\S+/gi, + /api[_-]?key\s*[:=]\s*\S+/gi, + /\/Users\/[a-zA-Z0-9._-]+\//g, + /\/home\/[a-zA-Z0-9._-]+\//g, + /ghp_[a-zA-Z0-9]{36}/g, + /gho_[a-zA-Z0-9]{36}/g, + /xoxb-[a-zA-Z0-9-]+/g, + ]; + + let redactedCount = 0; + + function redactSensitive(text) { + if (typeof text !== 'string') return text; + let result = text; + for (const pattern of SENSITIVE_PATTERNS) { + pattern.lastIndex = 0; + const matches = result.match(pattern); + if (matches) { + redactedCount += matches.length; + result = result.replace(pattern, '[REDACTED]'); + } + } + return result; + } + + for (const dimKey of Object.keys(analysis.dimensions)) { + const dim = analysis.dimensions[dimKey]; + if (dim.evidence && Array.isArray(dim.evidence)) { + for (let i = 0; i < dim.evidence.length; i++) { + const ev = dim.evidence[i]; + if (ev.quote) ev.quote = redactSensitive(ev.quote); + if (ev.example) ev.example = redactSensitive(ev.example); + if (ev.signal) ev.signal = redactSensitive(ev.signal); + } + } + } + + if (redactedCount > 0) { + process.stderr.write(`Sensitive content redacted: ${redactedCount} pattern(s) removed from evidence quotes\n`); + } + + const templatePath = path.join(__dirname, '..', '..', 'templates', 'user-profile.md'); + if (!fs.existsSync(templatePath)) error(`Template not found: ${templatePath}`); + let template = fs.readFileSync(templatePath, 'utf-8'); + + const dimensionLabels = { + communication_style: 'Communication', + decision_speed: 'Decisions', + explanation_depth: 'Explanations', + debugging_approach: 'Debugging', + ux_philosophy: 'UX Philosophy', + vendor_philosophy: 'Vendor Philosophy', + frustration_triggers: 'Frustration Triggers', + learning_style: 'Learning Style', + }; + + const summaryLines = []; + let highCount = 0, mediumCount = 0, lowCount = 0, dimensionsScored = 0; + + for (const dimKey of DIMENSION_KEYS) { + const dim = analysis.dimensions[dimKey]; + if (!dim) continue; + const conf = (dim.confidence || '').toUpperCase(); + if (conf === 'HIGH' || conf === 'MEDIUM' || conf === 'LOW') dimensionsScored++; + if (conf === 'HIGH') { + highCount++; + if (dim.claude_instruction) summaryLines.push(`- **${dimensionLabels[dimKey] || dimKey}:** ${dim.claude_instruction} (HIGH)`); + } else if (conf === 'MEDIUM') { + mediumCount++; + if (dim.claude_instruction) summaryLines.push(`- **${dimensionLabels[dimKey] || dimKey}:** ${dim.claude_instruction} (MEDIUM)`); + } else if (conf === 'LOW') { + lowCount++; + } + } + + const summaryInstructions = summaryLines.length > 0 + ? summaryLines.join('\n') + : '- No high or medium confidence dimensions scored yet.'; + + template = template.replace(/\{\{generated_at\}\}/g, new Date().toISOString()); + template = template.replace(/\{\{data_source\}\}/g, analysis.data_source || 'session_analysis'); + template = template.replace(/\{\{projects_list\}\}/g, (analysis.projects_list || analysis.projects_analyzed || []).join(', ')); + template = template.replace(/\{\{message_count\}\}/g, String(analysis.message_count || analysis.messages_analyzed || 0)); + template = template.replace(/\{\{summary_instructions\}\}/g, summaryInstructions); + template = template.replace(/\{\{profile_version\}\}/g, analysis.profile_version); + template = template.replace(/\{\{projects_count\}\}/g, String((analysis.projects_list || analysis.projects_analyzed || []).length)); + template = template.replace(/\{\{dimensions_scored\}\}/g, String(dimensionsScored)); + template = template.replace(/\{\{high_confidence_count\}\}/g, String(highCount)); + template = template.replace(/\{\{medium_confidence_count\}\}/g, String(mediumCount)); + template = template.replace(/\{\{low_confidence_count\}\}/g, String(lowCount)); + template = template.replace(/\{\{sensitive_excluded_summary\}\}/g, + redactedCount > 0 ? `${redactedCount} pattern(s) redacted` : 'None detected'); + + for (const dimKey of DIMENSION_KEYS) { + const dim = analysis.dimensions[dimKey] || {}; + const rating = dim.rating || 'UNSCORED'; + const confidence = dim.confidence || 'UNSCORED'; + const instruction = dim.claude_instruction || 'No strong preference detected. Ask the developer when this dimension is relevant.'; + const summary = dim.summary || ''; + + let evidenceBlock = ''; + const evidenceArr = dim.evidence_quotes || dim.evidence; + if (evidenceArr && Array.isArray(evidenceArr) && evidenceArr.length > 0) { + const evidenceLines = evidenceArr.map(ev => { + const signal = ev.signal || ev.pattern || ''; + const quote = ev.quote || ev.example || ''; + const project = ev.project || 'unknown'; + return `- **Signal:** ${signal} / **Example:** "${quote}" -- project: ${project}`; + }); + evidenceBlock = evidenceLines.join('\n'); + } else { + evidenceBlock = '- No evidence collected for this dimension.'; + } + + template = template.replace(new RegExp(`\\{\\{${dimKey}\\.rating\\}\\}`, 'g'), rating); + template = template.replace(new RegExp(`\\{\\{${dimKey}\\.confidence\\}\\}`, 'g'), confidence); + template = template.replace(new RegExp(`\\{\\{${dimKey}\\.claude_instruction\\}\\}`, 'g'), instruction); + template = template.replace(new RegExp(`\\{\\{${dimKey}\\.summary\\}\\}`, 'g'), summary); + template = template.replace(new RegExp(`\\{\\{${dimKey}\\.evidence\\}\\}`, 'g'), evidenceBlock); + } + + let outputPath = options.output; + if (!outputPath) { + outputPath = path.join(os.homedir(), '.OpenCode', 'get-shit-done', 'USER-PROFILE.md'); + } else if (!path.isAbsolute(outputPath)) { + outputPath = path.join(cwd, outputPath); + } + + fs.mkdirSync(path.dirname(outputPath), { recursive: true }); + fs.writeFileSync(outputPath, template, 'utf-8'); + + const result = { + profile_path: outputPath, + dimensions_scored: dimensionsScored, + high_confidence: highCount, + medium_confidence: mediumCount, + low_confidence: lowCount, + sensitive_redacted: redactedCount, + source: analysis.data_source || 'session_analysis', + }; + + output(result, raw); +} + +function cmdProfileQuestionnaire(options, raw) { + if (!options.answers) { + const questionsOutput = { + mode: 'interactive', + questions: PROFILING_QUESTIONS.map(q => ({ + dimension: q.dimension, + header: q.header, + context: q.context, + question: q.question, + options: q.options.map(o => ({ label: o.label, value: o.value })), + })), + }; + output(questionsOutput, raw); + return; + } + + const answerValues = options.answers.split(',').map(a => a.trim()); + if (answerValues.length !== PROFILING_QUESTIONS.length) { + error(`Expected ${PROFILING_QUESTIONS.length} answers (comma-separated), got ${answerValues.length}`); + } + + const analysis = { + profile_version: '1.0', + analyzed_at: new Date().toISOString(), + data_source: 'questionnaire', + projects_analyzed: [], + messages_analyzed: 0, + message_threshold: 'questionnaire', + sensitive_excluded: [], + dimensions: {}, + }; + + for (let i = 0; i < PROFILING_QUESTIONS.length; i++) { + const question = PROFILING_QUESTIONS[i]; + const answerValue = answerValues[i]; + const selectedOption = question.options.find(o => o.value === answerValue); + + if (!selectedOption) { + error(`Invalid answer "${answerValue}" for ${question.dimension}. Valid values: ${question.options.map(o => o.value).join(', ')}`); + } + + const ambiguous = isAmbiguousAnswer(question.dimension, answerValue); + + analysis.dimensions[question.dimension] = { + rating: selectedOption.rating, + confidence: ambiguous ? 'LOW' : 'MEDIUM', + evidence_count: 1, + cross_project_consistent: null, + evidence: [{ + signal: 'Self-reported via questionnaire', + quote: selectedOption.label, + project: 'N/A (questionnaire)', + }], + summary: `Developer self-reported as ${selectedOption.rating} for ${question.header.toLowerCase()}.`, + claude_instruction: generateClaudeInstruction(question.dimension, selectedOption.rating), + }; + } + + output(analysis, raw); +} + +function cmdGenerateDevPreferences(cwd, options, raw) { + if (!options.analysis) error('--analysis is required'); + + let analysisPath = options.analysis; + if (!path.isAbsolute(analysisPath)) analysisPath = path.join(cwd, analysisPath); + if (!fs.existsSync(analysisPath)) error(`Analysis file not found: ${analysisPath}`); + + let analysis; + try { + analysis = JSON.parse(fs.readFileSync(analysisPath, 'utf-8')); + } catch (err) { + error(`Failed to parse analysis JSON: ${err.message}`); + } + + if (!analysis.dimensions || typeof analysis.dimensions !== 'object') { + error('Analysis JSON must contain a "dimensions" object'); + } + + const devPrefLabels = { + communication_style: 'Communication', + decision_speed: 'Decision Support', + explanation_depth: 'Explanations', + debugging_approach: 'Debugging', + ux_philosophy: 'UX Approach', + vendor_philosophy: 'Library & Tool Choices', + frustration_triggers: 'Boundaries', + learning_style: 'Learning Support', + }; + + const templatePath = path.join(__dirname, '..', '..', 'templates', 'dev-preferences.md'); + if (!fs.existsSync(templatePath)) error(`Template not found: ${templatePath}`); + let template = fs.readFileSync(templatePath, 'utf-8'); + + const directiveLines = []; + const dimensionsIncluded = []; + + for (const dimKey of DIMENSION_KEYS) { + const dim = analysis.dimensions[dimKey]; + if (!dim) continue; + const label = devPrefLabels[dimKey] || dimKey; + const confidence = dim.confidence || 'UNSCORED'; + let instruction = dim.claude_instruction; + if (!instruction) { + const lookup = CLAUDE_INSTRUCTIONS[dimKey]; + if (lookup && dim.rating && lookup[dim.rating]) { + instruction = lookup[dim.rating]; + } else { + instruction = `Adapt to this developer's ${dimKey.replace(/_/g, ' ')} preference.`; + } + } + directiveLines.push(`### ${label}\n${instruction} (${confidence} confidence)\n`); + dimensionsIncluded.push(dimKey); + } + + const directivesBlock = directiveLines.join('\n').trim(); + template = template.replace(/\{\{behavioral_directives\}\}/g, directivesBlock); + template = template.replace(/\{\{generated_at\}\}/g, new Date().toISOString()); + template = template.replace(/\{\{data_source\}\}/g, analysis.data_source || 'session_analysis'); + + let stackBlock; + if (analysis.data_source === 'questionnaire') { + stackBlock = 'Stack preferences not available (questionnaire-only profile). Run `/gsd-profile-user --refresh` with session data to populate.'; + } else if (options.stack) { + stackBlock = options.stack; + } else { + stackBlock = 'Stack preferences will be populated from session analysis.'; + } + template = template.replace(/\{\{stack_preferences\}\}/g, stackBlock); + + let outputPath = options.output; + if (!outputPath) { + outputPath = path.join(os.homedir(), '.OpenCode', 'commands', 'gsd', 'dev-preferences.md'); + } else if (!path.isAbsolute(outputPath)) { + outputPath = path.join(cwd, outputPath); + } + + fs.mkdirSync(path.dirname(outputPath), { recursive: true }); + fs.writeFileSync(outputPath, template, 'utf-8'); + + const result = { + command_path: outputPath, + command_name: '/gsd-dev-preferences', + dimensions_included: dimensionsIncluded, + source: analysis.data_source || 'session_analysis', + }; + + output(result, raw); +} + +function cmdGenerateClaudeProfile(cwd, options, raw) { + if (!options.analysis) error('--analysis is required'); + + let analysisPath = options.analysis; + if (!path.isAbsolute(analysisPath)) analysisPath = path.join(cwd, analysisPath); + if (!fs.existsSync(analysisPath)) error(`Analysis file not found: ${analysisPath}`); + + let analysis; + try { + analysis = JSON.parse(fs.readFileSync(analysisPath, 'utf-8')); + } catch (err) { + error(`Failed to parse analysis JSON: ${err.message}`); + } + + if (!analysis.dimensions || typeof analysis.dimensions !== 'object') { + error('Analysis JSON must contain a "dimensions" object'); + } + + const profileLabels = { + communication_style: 'Communication', + decision_speed: 'Decisions', + explanation_depth: 'Explanations', + debugging_approach: 'Debugging', + ux_philosophy: 'UX Philosophy', + vendor_philosophy: 'Vendor Choices', + frustration_triggers: 'Frustrations', + learning_style: 'Learning', + }; + + const dataSource = analysis.data_source || 'session_analysis'; + const tableRows = []; + const directiveLines = []; + const dimensionsIncluded = []; + + for (const dimKey of DIMENSION_KEYS) { + const dim = analysis.dimensions[dimKey]; + if (!dim) continue; + const label = profileLabels[dimKey] || dimKey; + const rating = dim.rating || 'UNSCORED'; + const confidence = dim.confidence || 'UNSCORED'; + tableRows.push(`| ${label} | ${rating} | ${confidence} |`); + let instruction = dim.claude_instruction; + if (!instruction) { + const lookup = CLAUDE_INSTRUCTIONS[dimKey]; + if (lookup && dim.rating && lookup[dim.rating]) { + instruction = lookup[dim.rating]; + } else { + instruction = `Adapt to this developer's ${dimKey.replace(/_/g, ' ')} preference.`; + } + } + directiveLines.push(`- **${label}:** ${instruction}`); + dimensionsIncluded.push(dimKey); + } + + const sectionLines = [ + '', + '## Developer Profile', + '', + `> Generated by GSD from ${dataSource}. Run \`/gsd-profile-user --refresh\` to update.`, + '', + '| Dimension | Rating | Confidence |', + '|-----------|--------|------------|', + ...tableRows, + '', + '**Directives:**', + ...directiveLines, + '', + ]; + + const sectionContent = sectionLines.join('\n'); + + let targetPath; + if (options.global) { + targetPath = path.join(os.homedir(), '.OpenCode', 'AGENTS.md'); + } else if (options.output) { + targetPath = path.isAbsolute(options.output) ? options.output : path.join(cwd, options.output); + } else { + targetPath = path.join(cwd, 'AGENTS.md'); + } + + let action; + + if (fs.existsSync(targetPath)) { + let existingContent = fs.readFileSync(targetPath, 'utf-8'); + const startMarker = ''; + const endMarker = ''; + const startIdx = existingContent.indexOf(startMarker); + const endIdx = existingContent.indexOf(endMarker); + + if (startIdx !== -1 && endIdx !== -1) { + const before = existingContent.substring(0, startIdx); + const after = existingContent.substring(endIdx + endMarker.length); + existingContent = before + sectionContent + after; + action = 'updated'; + } else { + existingContent = existingContent.trimEnd() + '\n\n' + sectionContent + '\n'; + action = 'appended'; + } + fs.writeFileSync(targetPath, existingContent, 'utf-8'); + } else { + fs.mkdirSync(path.dirname(targetPath), { recursive: true }); + fs.writeFileSync(targetPath, sectionContent + '\n', 'utf-8'); + action = 'created'; + } + + const result = { + claude_md_path: targetPath, + action, + dimensions_included: dimensionsIncluded, + is_global: !!options.global, + }; + + output(result, raw); +} + +function cmdGenerateClaudeMd(cwd, options, raw) { + const MANAGED_SECTIONS = ['project', 'stack', 'conventions', 'architecture', 'workflow']; + const generators = { + project: generateProjectSection, + stack: generateStackSection, + conventions: generateConventionsSection, + architecture: generateArchitectureSection, + workflow: generateWorkflowSection, + }; + const sectionHeadings = { + project: '## Project', + stack: '## Technology Stack', + conventions: '## Conventions', + architecture: '## Architecture', + workflow: '## GSD Workflow Enforcement', + }; + + const generated = {}; + const sectionsGenerated = []; + const sectionsFallback = []; + const sectionsSkipped = []; + + for (const name of MANAGED_SECTIONS) { + const gen = generators[name](cwd); + generated[name] = gen; + if (gen.hasFallback) { + sectionsFallback.push(name); + } else { + sectionsGenerated.push(name); + } + } + + let outputPath = options.output; + if (!outputPath) { + outputPath = path.join(cwd, 'AGENTS.md'); + } else if (!path.isAbsolute(outputPath)) { + outputPath = path.join(cwd, outputPath); + } + + let existingContent = safeReadFile(outputPath); + let action; + + if (existingContent === null) { + const sections = []; + for (const name of MANAGED_SECTIONS) { + const gen = generated[name]; + const heading = sectionHeadings[name]; + const body = `${heading}\n\n${gen.content}`; + sections.push(buildSection(name, gen.source, body)); + } + sections.push(''); + sections.push(CLAUDE_MD_PROFILE_PLACEHOLDER); + existingContent = sections.join('\n\n') + '\n'; + action = 'created'; + fs.mkdirSync(path.dirname(outputPath), { recursive: true }); + fs.writeFileSync(outputPath, existingContent, 'utf-8'); + } else { + action = 'updated'; + let fileContent = existingContent; + + for (const name of MANAGED_SECTIONS) { + const gen = generated[name]; + const heading = sectionHeadings[name]; + const body = `${heading}\n\n${gen.content}`; + const fullSection = buildSection(name, gen.source, body); + const hasMarkers = fileContent.indexOf(`)?\n([\s\S]*?)(?=\n##\s|$)/i); + if (!currentTestMatch) { + error('UAT file is missing a Current Test section'); + } + + const section = currentTestMatch[1].trimEnd(); + if (!section.trim()) { + error('Current Test section is empty'); + } + + if (/\[testing complete\]/i.test(section)) { + return { complete: true }; + } + + const numberMatch = section.match(/^number:\s*(\d+)\s*$/m); + const nameMatch = section.match(/^name:\s*(.+)\s*$/m); + const expectedBlockMatch = section.match(/^expected:\s*\|\n([\s\S]*?)(?=^\w[\w-]*:\s)/m) + || section.match(/^expected:\s*\|\n([\s\S]+)/m); + const expectedInlineMatch = section.match(/^expected:\s*(.+)\s*$/m); + + if (!numberMatch || !nameMatch || (!expectedBlockMatch && !expectedInlineMatch)) { + error('Current Test section is malformed'); + } + + let expected; + if (expectedBlockMatch) { + expected = expectedBlockMatch[1] + .split('\n') + .map(line => line.replace(/^ {2}/, '')) + .join('\n') + .trim(); + } else { + expected = expectedInlineMatch[1].trim(); + } + + return { + complete: false, + number: parseInt(numberMatch[1], 10), + name: sanitizeForDisplay(nameMatch[1].trim()), + expected: sanitizeForDisplay(expected), + }; +} + +function buildCheckpoint(currentTest) { + return [ + '╔══════════════════════════════════════════════════════════════╗', + '║ CHECKPOINT: Verification Required ║', + '╚══════════════════════════════════════════════════════════════╝', + '', + `**Test ${currentTest.number}: ${currentTest.name}**`, + '', + currentTest.expected, + '', + '──────────────────────────────────────────────────────────────', + 'Type `pass` or describe what\'s wrong.', + '──────────────────────────────────────────────────────────────', + ].join('\n'); +} + +function parseUatItems(content) { + const items = []; + // Match test blocks: ### N. Name\nexpected: ...\nresult: ...\n + const testPattern = /###\s*(\d+)\.\s*([^\n]+)\nexpected:\s*([^\n]+)\nresult:\s*(\w+)(?:\n(?:reported|reason|blocked_by):\s*[^\n]*)?/g; + let match; + while ((match = testPattern.exec(content)) !== null) { + const [, num, name, expected, result] = match; + if (result === 'pending' || result === 'skipped' || result === 'blocked') { + // Extract optional fields — limit to current test block (up to next ### or EOF) + const afterMatch = content.slice(match.index); + const nextHeading = afterMatch.indexOf('\n###', 1); + const blockText = nextHeading > 0 ? afterMatch.slice(0, nextHeading) : afterMatch; + const reasonMatch = blockText.match(/reason:\s*(.+)/); + const blockedByMatch = blockText.match(/blocked_by:\s*(.+)/); + + const item = { + test: parseInt(num, 10), + name: name.trim(), + expected: expected.trim(), + result, + category: categorizeItem(result, reasonMatch?.[1], blockedByMatch?.[1]), + }; + if (reasonMatch) item.reason = reasonMatch[1].trim(); + if (blockedByMatch) item.blocked_by = blockedByMatch[1].trim(); + items.push(item); + } + } + return items; +} + +function parseVerificationItems(content, status) { + const items = []; + if (status === 'human_needed') { + // Extract from human_verification section — look for numbered items or table rows + const hvSection = content.match(/##\s*Human Verification.*?\n([\s\S]*?)(?=\n##\s|\n---\s|$)/i); + if (hvSection) { + const lines = hvSection[1].split('\n'); + for (const line of lines) { + // Match table rows: | N | description | ... | + const tableMatch = line.match(/\|\s*(\d+)\s*\|\s*([^|]+)/); + // Match bullet items: - description + const bulletMatch = line.match(/^[-*]\s+(.+)/); + // Match numbered items: 1. description + const numberedMatch = line.match(/^(\d+)\.\s+(.+)/); + + if (tableMatch) { + items.push({ + test: parseInt(tableMatch[1], 10), + name: tableMatch[2].trim(), + result: 'human_needed', + category: 'human_uat', + }); + } else if (numberedMatch) { + items.push({ + test: parseInt(numberedMatch[1], 10), + name: numberedMatch[2].trim(), + result: 'human_needed', + category: 'human_uat', + }); + } else if (bulletMatch && bulletMatch[1].length > 10) { + items.push({ + name: bulletMatch[1].trim(), + result: 'human_needed', + category: 'human_uat', + }); + } + } + } + } + // gaps_found items are already handled by plan-phase --gaps pipeline + return items; +} + +function categorizeItem(result, reason, blockedBy) { + if (result === 'blocked' || blockedBy) { + if (blockedBy) { + if (/server/i.test(blockedBy)) return 'server_blocked'; + if (/device|physical/i.test(blockedBy)) return 'device_needed'; + if (/build|release|preview/i.test(blockedBy)) return 'build_needed'; + if (/third.party|twilio|stripe/i.test(blockedBy)) return 'third_party'; + } + return 'blocked'; + } + if (result === 'skipped') { + if (reason) { + if (/server|not running|not available/i.test(reason)) return 'server_blocked'; + if (/simulator|physical|device/i.test(reason)) return 'device_needed'; + if (/build|release|preview/i.test(reason)) return 'build_needed'; + } + return 'skipped_unresolved'; + } + if (result === 'pending') return 'pending'; + if (result === 'human_needed') return 'human_uat'; + return 'unknown'; +} + +module.exports = { + cmdAuditUat, + cmdRenderCheckpoint, + parseCurrentTest, + buildCheckpoint, +}; diff --git a/gsd-opencode/get-shit-done/bin/lib/verify.cjs b/gsd-opencode/get-shit-done/bin/lib/verify.cjs index 834f39c..7d40d96 100644 --- a/gsd-opencode/get-shit-done/bin/lib/verify.cjs +++ b/gsd-opencode/get-shit-done/bin/lib/verify.cjs @@ -4,7 +4,8 @@ const fs = require('fs'); const path = require('path'); -const { safeReadFile, normalizePhaseName, execGit, findPhaseInternal, getMilestoneInfo, output, error } = require('./core.cjs'); +const os = require('os'); +const { safeReadFile, loadConfig, normalizePhaseName, execGit, findPhaseInternal, getMilestoneInfo, stripShippedMilestones, extractCurrentMilestone, planningDir, planningRoot, output, error, checkAgentsInstalled } = require('./core.cjs'); const { extractFrontmatter, parseMustHavesBlock } = require('./frontmatter.cjs'); const { writeStateMd } = require('./state.cjs'); @@ -395,8 +396,8 @@ function cmdVerifyKeyLinks(cwd, planFilePath, raw) { } function cmdValidateConsistency(cwd, raw) { - const roadmapPath = path.join(cwd, '.planning', 'ROADMAP.md'); - const phasesDir = path.join(cwd, '.planning', 'phases'); + const roadmapPath = path.join(planningDir(cwd), 'ROADMAP.md'); + const phasesDir = path.join(planningDir(cwd), 'phases'); const errors = []; const warnings = []; @@ -407,9 +408,10 @@ function cmdValidateConsistency(cwd, raw) { return; } - const roadmapContent = fs.readFileSync(roadmapPath, 'utf-8'); + const roadmapContentRaw = fs.readFileSync(roadmapPath, 'utf-8'); + const roadmapContent = extractCurrentMilestone(roadmapContentRaw, cwd); - // Extract phases from ROADMAP + // Extract phases from ROADMAP (archived milestones already stripped) const roadmapPhases = new Set(); const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:/gi; let m; @@ -426,7 +428,7 @@ function cmdValidateConsistency(cwd, raw) { const dm = dir.match(/^(\d+[A-Z]?(?:\.\d+)*)/i); if (dm) diskPhases.add(dm[1]); } - } catch {} + } catch { /* intentionally empty */ } // Check: phases in ROADMAP but not on disk for (const p of roadmapPhases) { @@ -443,15 +445,18 @@ function cmdValidateConsistency(cwd, raw) { } } - // Check: sequential phase numbers (integers only) - const integerPhases = [...diskPhases] - .filter(p => !p.includes('.')) - .map(p => parseInt(p, 10)) - .sort((a, b) => a - b); + // Check: sequential phase numbers (integers only, skip in custom naming mode) + const config = loadConfig(cwd); + if (config.phase_naming !== 'custom') { + const integerPhases = [...diskPhases] + .filter(p => !p.includes('.')) + .map(p => parseInt(p, 10)) + .sort((a, b) => a - b); - for (let i = 1; i < integerPhases.length; i++) { - if (integerPhases[i] !== integerPhases[i - 1] + 1) { - warnings.push(`Gap in phase numbering: ${integerPhases[i - 1]} → ${integerPhases[i]}`); + for (let i = 1; i < integerPhases.length; i++) { + if (integerPhases[i] !== integerPhases[i - 1] + 1) { + warnings.push(`Gap in phase numbering: ${integerPhases[i - 1]} → ${integerPhases[i]}`); + } } } @@ -488,7 +493,7 @@ function cmdValidateConsistency(cwd, raw) { } } } - } catch {} + } catch { /* intentionally empty */ } // Check: frontmatter in plans has required fields try { @@ -508,19 +513,33 @@ function cmdValidateConsistency(cwd, raw) { } } } - } catch {} + } catch { /* intentionally empty */ } const passed = errors.length === 0; output({ passed, errors, warnings, warning_count: warnings.length }, raw, passed ? 'passed' : 'failed'); } function cmdValidateHealth(cwd, options, raw) { - const planningDir = path.join(cwd, '.planning'); - const projectPath = path.join(planningDir, 'PROJECT.md'); - const roadmapPath = path.join(planningDir, 'ROADMAP.md'); - const statePath = path.join(planningDir, 'STATE.md'); - const configPath = path.join(planningDir, 'config.json'); - const phasesDir = path.join(planningDir, 'phases'); + // Guard: detect if CWD is the home directory (likely accidental) + const resolved = path.resolve(cwd); + if (resolved === os.homedir()) { + output({ + status: 'error', + errors: [{ code: 'E010', message: `CWD is home directory (${resolved}) — health check would read the wrong .planning/ directory. Run from your project root instead.`, fix: 'cd into your project directory and retry' }], + warnings: [], + info: [{ code: 'I010', message: `Resolved CWD: ${resolved}` }], + repairable_count: 0, + }, raw); + return; + } + + const planBase = planningDir(cwd); + const planRoot = planningRoot(cwd); + const projectPath = path.join(planRoot, 'PROJECT.md'); + const roadmapPath = path.join(planBase, 'ROADMAP.md'); + const statePath = path.join(planBase, 'STATE.md'); + const configPath = path.join(planRoot, 'config.json'); + const phasesDir = path.join(planBase, 'phases'); const errors = []; const warnings = []; @@ -536,7 +555,7 @@ function cmdValidateHealth(cwd, options, raw) { }; // ─── Check 1: .planning/ exists ─────────────────────────────────────────── - if (!fs.existsSync(planningDir)) { + if (!fs.existsSync(planBase)) { addIssue('error', 'E001', '.planning/ directory not found', 'Run /gsd-new-project to initialize'); output({ status: 'broken', @@ -584,15 +603,19 @@ function cmdValidateHealth(cwd, options, raw) { if (m) diskPhases.add(m[1]); } } - } catch {} + } catch { /* intentionally empty */ } // Check for invalid references for (const ref of phaseRefs) { const normalizedRef = String(parseInt(ref, 10)).padStart(2, '0'); if (!diskPhases.has(ref) && !diskPhases.has(normalizedRef) && !diskPhases.has(String(parseInt(ref, 10)))) { // Only warn if phases dir has any content (not just an empty project) if (diskPhases.size > 0) { - addIssue('warning', 'W002', `STATE.md references phase ${ref}, but only phases ${[...diskPhases].sort().join(', ')} exist`, 'Run /gsd-health --repair to regenerate STATE.md', true); - if (!repairs.includes('regenerateState')) repairs.push('regenerateState'); + addIssue( + 'warning', + 'W002', + `STATE.md references phase ${ref}, but only phases ${[...diskPhases].sort().join(', ')} exist`, + 'Review STATE.md manually before changing it; /gsd-health --repair will not overwrite an existing STATE.md for phase mismatches' + ); } } } @@ -607,7 +630,7 @@ function cmdValidateHealth(cwd, options, raw) { const raw = fs.readFileSync(configPath, 'utf-8'); const parsed = JSON.parse(raw); // Validate known fields - const validProfiles = ['quality', 'balanced', 'budget']; + const validProfiles = ['quality', 'balanced', 'budget', 'inherit']; if (parsed.model_profile && !validProfiles.includes(parsed.model_profile)) { addIssue('warning', 'W004', `config.json: invalid model_profile "${parsed.model_profile}"`, `Valid values: ${validProfiles.join(', ')}`); } @@ -626,7 +649,7 @@ function cmdValidateHealth(cwd, options, raw) { addIssue('warning', 'W008', 'config.json: workflow.nyquist_validation absent (defaults to enabled but agents may skip)', 'Run /gsd-health --repair to add key', true); if (!repairs.includes('addNyquistKey')) repairs.push('addNyquistKey'); } - } catch {} + } catch { /* intentionally empty */ } } // ─── Check 6: Phase directory naming (NN-name format) ───────────────────── @@ -637,7 +660,7 @@ function cmdValidateHealth(cwd, options, raw) { addIssue('warning', 'W005', `Phase directory "${e.name}" doesn't follow NN-name format`, 'Rename to match pattern (e.g., 01-setup)'); } } - } catch {} + } catch { /* intentionally empty */ } // ─── Check 7: Orphaned plans (PLAN without SUMMARY) ─────────────────────── try { @@ -656,7 +679,7 @@ function cmdValidateHealth(cwd, options, raw) { } } } - } catch {} + } catch { /* intentionally empty */ } // ─── Check 7b: Nyquist VALIDATION.md consistency ──────────────────────── try { @@ -674,12 +697,31 @@ function cmdValidateHealth(cwd, options, raw) { } } } - } catch {} + } catch { /* intentionally empty */ } + + // ─── Check 7c: Agent installation (#1371) ────────────────────────────────── + // Verify GSD agents are installed. Missing agents cause task(subagent_type=...) + // to silently fall back to general-purpose, losing specialized instructions. + try { + const agentStatus = checkAgentsInstalled(); + if (!agentStatus.agents_installed) { + if (agentStatus.installed_agents.length === 0) { + addIssue('warning', 'W010', + `No GSD agents found in ${agentStatus.agents_dir} — task(subagent_type="gsd-*") will fall back to general-purpose`, + 'Run the GSD installer: npx gsd-opencode@latest'); + } else { + addIssue('warning', 'W010', + `Missing ${agentStatus.missing_agents.length} GSD agents: ${agentStatus.missing_agents.join(', ')} — affected workflows will fall back to general-purpose`, + 'Run the GSD installer: npx gsd-opencode@latest'); + } + } + } catch { /* intentionally empty — agent check is non-blocking */ } // ─── Check 8: Run existing consistency checks ───────────────────────────── // Inline subset of cmdValidateConsistency if (fs.existsSync(roadmapPath)) { - const roadmapContent = fs.readFileSync(roadmapPath, 'utf-8'); + const roadmapContentRaw = fs.readFileSync(roadmapPath, 'utf-8'); + const roadmapContent = extractCurrentMilestone(roadmapContentRaw, cwd); const roadmapPhases = new Set(); const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:/gi; let m; @@ -696,7 +738,7 @@ function cmdValidateHealth(cwd, options, raw) { if (dm) diskPhases.add(dm[1]); } } - } catch {} + } catch { /* intentionally empty */ } // Phases in ROADMAP but not on disk for (const p of roadmapPhases) { @@ -728,10 +770,17 @@ function cmdValidateHealth(cwd, options, raw) { commit_docs: true, search_gitignored: false, branching_strategy: 'none', - research: true, - plan_checker: true, - verifier: true, + phase_branch_template: 'gsd/phase-{phase}-{slug}', + milestone_branch_template: 'gsd/{milestone}-{slug}', + quick_branch_template: null, + workflow: { + research: true, + plan_check: true, + verifier: true, + nyquist_validation: true, + }, parallelization: true, + brave_search: false, }; fs.writeFileSync(configPath, JSON.stringify(defaults, null, 2), 'utf-8'); repairActions.push({ action: repair, success: true, path: 'config.json' }); @@ -807,6 +856,24 @@ function cmdValidateHealth(cwd, options, raw) { }, raw); } +/** + * Validate agent installation status (#1371). + * Returns detailed information about which agents are installed and which are missing. + */ +function cmdValidateAgents(cwd, raw) { + const { MODEL_PROFILES } = require('./model-profiles.cjs'); + const agentStatus = checkAgentsInstalled(); + const expected = Object.keys(MODEL_PROFILES); + + output({ + agents_dir: agentStatus.agents_dir, + agents_found: agentStatus.agents_installed, + installed: agentStatus.installed_agents, + missing: agentStatus.missing_agents, + expected, + }, raw); +} + module.exports = { cmdVerifySummary, cmdVerifyPlanStructure, @@ -817,4 +884,5 @@ module.exports = { cmdVerifyKeyLinks, cmdValidateConsistency, cmdValidateHealth, + cmdValidateAgents, }; diff --git a/gsd-opencode/get-shit-done/bin/lib/workstream.cjs b/gsd-opencode/get-shit-done/bin/lib/workstream.cjs new file mode 100644 index 0000000..868b75e --- /dev/null +++ b/gsd-opencode/get-shit-done/bin/lib/workstream.cjs @@ -0,0 +1,491 @@ +/** + * Workstream — CRUD operations for workstream namespacing + * + * Workstreams enable parallel milestones by scoping ROADMAP.md, STATE.md, + * REQUIREMENTS.md, and phases/ into .planning/workstreams/{name}/ directories. + * + * When no workstreams/ directory exists, GSD operates in "flat mode" with + * everything at .planning/ — backward compatible with pre-workstream installs. + */ + +const fs = require('fs'); +const path = require('path'); +const { output, error, planningPaths, planningRoot, toPosixPath, getMilestoneInfo, generateSlugInternal, setActiveWorkstream, getActiveWorkstream, filterPlanFiles, filterSummaryFiles, readSubdirectories } = require('./core.cjs'); +const { stateExtractField } = require('./state.cjs'); + +// ─── Migration ────────────────────────────────────────────────────────────── + +/** + * Migrate flat .planning/ layout to workstream mode. + * Moves per-workstream files (ROADMAP.md, STATE.md, REQUIREMENTS.md, phases/) + * into .planning/workstreams/{name}/. Shared files (PROJECT.md, config.json, + * milestones/, research/, codebase/, todos/) stay in place. + */ +function migrateToWorkstreams(cwd, workstreamName) { + if (!workstreamName || /[/\\]/.test(workstreamName) || workstreamName === '.' || workstreamName === '..') { + throw new Error('Invalid workstream name for migration'); + } + + const baseDir = planningRoot(cwd); + const wsDir = path.join(baseDir, 'workstreams', workstreamName); + + if (fs.existsSync(path.join(baseDir, 'workstreams'))) { + throw new Error('Already in workstream mode — .planning/workstreams/ exists'); + } + + const toMove = [ + { name: 'ROADMAP.md', type: 'file' }, + { name: 'STATE.md', type: 'file' }, + { name: 'REQUIREMENTS.md', type: 'file' }, + { name: 'phases', type: 'dir' }, + ]; + + fs.mkdirSync(wsDir, { recursive: true }); + + const filesMoved = []; + try { + for (const item of toMove) { + const src = path.join(baseDir, item.name); + if (fs.existsSync(src)) { + const dest = path.join(wsDir, item.name); + fs.renameSync(src, dest); + filesMoved.push(item.name); + } + } + } catch (err) { + for (const name of filesMoved) { + try { fs.renameSync(path.join(wsDir, name), path.join(baseDir, name)); } catch {} + } + try { fs.rmSync(wsDir, { recursive: true }); } catch {} + try { fs.rmdirSync(path.join(baseDir, 'workstreams')); } catch {} + throw err; + } + + return { migrated: true, workstream: workstreamName, files_moved: filesMoved }; +} + +// ─── CRUD Commands ────────────────────────────────────────────────────────── + +function cmdWorkstreamCreate(cwd, name, options, raw) { + if (!name) { + error('workstream name required. Usage: workstream create '); + } + + const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, ''); + if (!slug) { + error('Invalid workstream name — must contain at least one alphanumeric character'); + } + + const baseDir = planningRoot(cwd); + if (!fs.existsSync(baseDir)) { + error('.planning/ directory not found — run /gsd-new-project first'); + } + + const wsRoot = path.join(baseDir, 'workstreams'); + const wsDir = path.join(wsRoot, slug); + + if (fs.existsSync(wsDir) && fs.existsSync(path.join(wsDir, 'STATE.md'))) { + output({ created: false, error: 'already_exists', workstream: slug, path: toPosixPath(path.relative(cwd, wsDir)) }, raw); + return; + } + + const isFlatMode = !fs.existsSync(wsRoot); + let migration = null; + if (isFlatMode && options.migrate !== false) { + const hasExistingWork = fs.existsSync(path.join(baseDir, 'ROADMAP.md')) || + fs.existsSync(path.join(baseDir, 'STATE.md')) || + fs.existsSync(path.join(baseDir, 'phases')); + + if (hasExistingWork) { + const migrateName = options.migrateName || null; + let existingWsName; + if (migrateName) { + existingWsName = migrateName; + } else { + try { + const milestone = getMilestoneInfo(cwd); + existingWsName = generateSlugInternal(milestone.name) || 'default'; + } catch { + existingWsName = 'default'; + } + } + + try { + migration = migrateToWorkstreams(cwd, existingWsName); + } catch (e) { + output({ created: false, error: 'migration_failed', message: e.message }, raw); + return; + } + } else { + fs.mkdirSync(wsRoot, { recursive: true }); + } + } + + fs.mkdirSync(wsDir, { recursive: true }); + fs.mkdirSync(path.join(wsDir, 'phases'), { recursive: true }); + + const today = new Date().toISOString().split('T')[0]; + const stateContent = [ + '---', + `workstream: ${slug}`, + `created: ${today}`, + '---', + '', + '# Project State', + '', + '## Current Position', + '**Status:** Not started', + '**Current Phase:** None', + `**Last Activity:** ${today}`, + '**Last Activity Description:** Workstream created', + '', + '## Progress', + '**Phases Complete:** 0', + '**Current Plan:** N/A', + '', + '## Session Continuity', + '**Stopped At:** N/A', + '**Resume File:** None', + '', + ].join('\n'); + + const statePath = path.join(wsDir, 'STATE.md'); + if (!fs.existsSync(statePath)) { + fs.writeFileSync(statePath, stateContent, 'utf-8'); + } + + setActiveWorkstream(cwd, slug); + + const relPath = toPosixPath(path.relative(cwd, wsDir)); + output({ + created: true, + workstream: slug, + path: relPath, + state_path: relPath + '/STATE.md', + phases_path: relPath + '/phases', + migration: migration || null, + active: true, + }, raw); +} + +function cmdWorkstreamList(cwd, raw) { + const wsRoot = path.join(planningRoot(cwd), 'workstreams'); + + if (!fs.existsSync(wsRoot)) { + output({ mode: 'flat', workstreams: [], message: 'No workstreams — operating in flat mode' }, raw); + return; + } + + const entries = fs.readdirSync(wsRoot, { withFileTypes: true }); + const workstreams = []; + + for (const entry of entries) { + if (!entry.isDirectory()) continue; + + const wsDir = path.join(wsRoot, entry.name); + const phasesDir = path.join(wsDir, 'phases'); + + const phaseDirs = readSubdirectories(phasesDir); + const phaseCount = phaseDirs.length; + let completedCount = 0; + for (const d of phaseDirs) { + try { + const phaseFiles = fs.readdirSync(path.join(phasesDir, d)); + const plans = filterPlanFiles(phaseFiles); + const summaries = filterSummaryFiles(phaseFiles); + if (plans.length > 0 && summaries.length >= plans.length) completedCount++; + } catch {} + } + + let status = 'unknown', currentPhase = null; + try { + const stateContent = fs.readFileSync(path.join(wsDir, 'STATE.md'), 'utf-8'); + status = stateExtractField(stateContent, 'Status') || 'unknown'; + currentPhase = stateExtractField(stateContent, 'Current Phase'); + } catch {} + + workstreams.push({ + name: entry.name, + path: toPosixPath(path.relative(cwd, wsDir)), + has_roadmap: fs.existsSync(path.join(wsDir, 'ROADMAP.md')), + has_state: fs.existsSync(path.join(wsDir, 'STATE.md')), + status, + current_phase: currentPhase, + phase_count: phaseCount, + completed_phases: completedCount, + }); + } + + output({ mode: 'workstream', workstreams, count: workstreams.length }, raw); +} + +function cmdWorkstreamStatus(cwd, name, raw) { + if (!name) error('workstream name required. Usage: workstream status '); + if (/[/\\]/.test(name) || name === '.' || name === '..') error('Invalid workstream name'); + + const wsDir = path.join(planningRoot(cwd), 'workstreams', name); + if (!fs.existsSync(wsDir)) { + output({ found: false, workstream: name }, raw); + return; + } + + const p = planningPaths(cwd, name); + const relPath = toPosixPath(path.relative(cwd, wsDir)); + + const files = { + roadmap: fs.existsSync(p.roadmap), + state: fs.existsSync(p.state), + requirements: fs.existsSync(p.requirements), + }; + + const phases = []; + for (const dir of readSubdirectories(p.phases).sort()) { + try { + const phaseFiles = fs.readdirSync(path.join(p.phases, dir)); + const plans = filterPlanFiles(phaseFiles); + const summaries = filterSummaryFiles(phaseFiles); + phases.push({ + directory: dir, + status: summaries.length >= plans.length && plans.length > 0 ? 'complete' : + plans.length > 0 ? 'in_progress' : 'pending', + plan_count: plans.length, + summary_count: summaries.length, + }); + } catch {} + } + + let stateInfo = {}; + try { + const stateContent = fs.readFileSync(p.state, 'utf-8'); + stateInfo = { + status: stateExtractField(stateContent, 'Status') || 'unknown', + current_phase: stateExtractField(stateContent, 'Current Phase'), + last_activity: stateExtractField(stateContent, 'Last Activity'), + }; + } catch {} + + output({ + found: true, + workstream: name, + path: relPath, + files, + phases, + phase_count: phases.length, + completed_phases: phases.filter(ph => ph.status === 'complete').length, + ...stateInfo, + }, raw); +} + +function cmdWorkstreamComplete(cwd, name, options, raw) { + if (!name) error('workstream name required. Usage: workstream complete '); + if (/[/\\]/.test(name) || name === '.' || name === '..') error('Invalid workstream name'); + + const root = planningRoot(cwd); + const wsRoot = path.join(root, 'workstreams'); + const wsDir = path.join(wsRoot, name); + + if (!fs.existsSync(wsDir)) { + output({ completed: false, error: 'not_found', workstream: name }, raw); + return; + } + + const active = getActiveWorkstream(cwd); + if (active === name) setActiveWorkstream(cwd, null); + + const archiveDir = path.join(root, 'milestones'); + const today = new Date().toISOString().split('T')[0]; + let archivePath = path.join(archiveDir, `ws-${name}-${today}`); + let suffix = 1; + while (fs.existsSync(archivePath)) { + archivePath = path.join(archiveDir, `ws-${name}-${today}-${suffix++}`); + } + + fs.mkdirSync(archivePath, { recursive: true }); + + const filesMoved = []; + try { + const entries = fs.readdirSync(wsDir, { withFileTypes: true }); + for (const entry of entries) { + fs.renameSync(path.join(wsDir, entry.name), path.join(archivePath, entry.name)); + filesMoved.push(entry.name); + } + } catch (err) { + for (const fname of filesMoved) { + try { fs.renameSync(path.join(archivePath, fname), path.join(wsDir, fname)); } catch {} + } + try { fs.rmSync(archivePath, { recursive: true }); } catch {} + if (active === name) setActiveWorkstream(cwd, name); + output({ completed: false, error: 'archive_failed', message: err.message, workstream: name }, raw); + return; + } + + try { fs.rmdirSync(wsDir); } catch {} + + let remainingWs = 0; + try { + remainingWs = fs.readdirSync(wsRoot, { withFileTypes: true }).filter(e => e.isDirectory()).length; + if (remainingWs === 0) fs.rmdirSync(wsRoot); + } catch {} + + output({ + completed: true, + workstream: name, + archived_to: toPosixPath(path.relative(cwd, archivePath)), + remaining_workstreams: remainingWs, + reverted_to_flat: remainingWs === 0, + }, raw); +} + +// ─── Active Workstream Commands ────────────────────────────────────────────── + +function cmdWorkstreamSet(cwd, name, raw) { + if (!name) { + setActiveWorkstream(cwd, null); + output({ active: null, cleared: true }, raw); + return; + } + + if (!/^[a-zA-Z0-9_-]+$/.test(name)) { + output({ active: null, error: 'invalid_name', message: 'Workstream name must be alphanumeric, hyphens, and underscores only' }, raw); + return; + } + + const wsDir = path.join(planningRoot(cwd), 'workstreams', name); + if (!fs.existsSync(wsDir)) { + output({ active: null, error: 'not_found', workstream: name }, raw); + return; + } + + setActiveWorkstream(cwd, name); + output({ active: name, set: true }, raw, name); +} + +function cmdWorkstreamGet(cwd, raw) { + const active = getActiveWorkstream(cwd); + const wsRoot = path.join(planningRoot(cwd), 'workstreams'); + output({ active, mode: fs.existsSync(wsRoot) ? 'workstream' : 'flat' }, raw, active || 'none'); +} + +function cmdWorkstreamProgress(cwd, raw) { + const root = planningRoot(cwd); + const wsRoot = path.join(root, 'workstreams'); + + if (!fs.existsSync(wsRoot)) { + output({ mode: 'flat', workstreams: [], message: 'No workstreams — operating in flat mode' }, raw); + return; + } + + const active = getActiveWorkstream(cwd); + const entries = fs.readdirSync(wsRoot, { withFileTypes: true }); + const workstreams = []; + + for (const entry of entries) { + if (!entry.isDirectory()) continue; + + const wsDir = path.join(wsRoot, entry.name); + const phasesDir = path.join(wsDir, 'phases'); + + const phaseDirsProgress = readSubdirectories(phasesDir); + const phaseCount = phaseDirsProgress.length; + let completedCount = 0, totalPlans = 0, completedPlans = 0; + for (const d of phaseDirsProgress) { + try { + const phaseFiles = fs.readdirSync(path.join(phasesDir, d)); + const plans = filterPlanFiles(phaseFiles); + const summaries = filterSummaryFiles(phaseFiles); + totalPlans += plans.length; + completedPlans += Math.min(summaries.length, plans.length); + if (plans.length > 0 && summaries.length >= plans.length) completedCount++; + } catch {} + } + + let roadmapPhaseCount = phaseCount; + try { + const roadmapContent = fs.readFileSync(path.join(wsDir, 'ROADMAP.md'), 'utf-8'); + const phaseMatches = roadmapContent.match(/^###?\s+Phase\s+\d/gm); + if (phaseMatches) roadmapPhaseCount = phaseMatches.length; + } catch {} + + let status = 'unknown', currentPhase = null; + try { + const stateContent = fs.readFileSync(path.join(wsDir, 'STATE.md'), 'utf-8'); + status = stateExtractField(stateContent, 'Status') || 'unknown'; + currentPhase = stateExtractField(stateContent, 'Current Phase'); + } catch {} + + workstreams.push({ + name: entry.name, + active: entry.name === active, + status, + current_phase: currentPhase, + phases: `${completedCount}/${roadmapPhaseCount}`, + plans: `${completedPlans}/${totalPlans}`, + progress_percent: roadmapPhaseCount > 0 ? Math.round((completedCount / roadmapPhaseCount) * 100) : 0, + }); + } + + output({ mode: 'workstream', active, workstreams, count: workstreams.length }, raw); +} + +// ─── Collision Detection ──────────────────────────────────────────────────── + +/** + * Return other workstreams that are NOT complete. + * Used to detect whether the milestone has active parallel work + * when a workstream finishes its last phase. + */ +function getOtherActiveWorkstreams(cwd, excludeWs) { + const wsRoot = path.join(planningRoot(cwd), 'workstreams'); + if (!fs.existsSync(wsRoot)) return []; + + const entries = fs.readdirSync(wsRoot, { withFileTypes: true }); + const others = []; + + for (const entry of entries) { + if (!entry.isDirectory() || entry.name === excludeWs) continue; + + const wsDir = path.join(wsRoot, entry.name); + const statePath = path.join(wsDir, 'STATE.md'); + + let status = 'unknown', currentPhase = null; + try { + const content = fs.readFileSync(statePath, 'utf-8'); + status = stateExtractField(content, 'Status') || 'unknown'; + currentPhase = stateExtractField(content, 'Current Phase'); + } catch {} + + if (status.toLowerCase().includes('milestone complete') || + status.toLowerCase().includes('archived')) { + continue; + } + + const phasesDir = path.join(wsDir, 'phases'); + const phaseDirsOther = readSubdirectories(phasesDir); + const phaseCount = phaseDirsOther.length; + let completedCount = 0; + for (const d of phaseDirsOther) { + try { + const phaseFiles = fs.readdirSync(path.join(phasesDir, d)); + const plans = filterPlanFiles(phaseFiles); + const summaries = filterSummaryFiles(phaseFiles); + if (plans.length > 0 && summaries.length >= plans.length) completedCount++; + } catch {} + } + + others.push({ name: entry.name, status, current_phase: currentPhase, phases: `${completedCount}/${phaseCount}` }); + } + + return others; +} + +module.exports = { + migrateToWorkstreams, + cmdWorkstreamCreate, + cmdWorkstreamList, + cmdWorkstreamStatus, + cmdWorkstreamComplete, + cmdWorkstreamSet, + cmdWorkstreamGet, + cmdWorkstreamProgress, + getOtherActiveWorkstreams, +}; diff --git a/gsd-opencode/get-shit-done/references/checkpoints.md b/gsd-opencode/get-shit-done/references/checkpoints.md index 11e0a60..69f0393 100644 --- a/gsd-opencode/get-shit-done/references/checkpoints.md +++ b/gsd-opencode/get-shit-done/references/checkpoints.md @@ -50,7 +50,7 @@ Plans execute autonomously. Checkpoints formalize interaction points where human Start dev server for verification Run `npm run dev` in background, wait for "ready" message, capture port - curl http://localhost:3000 returns 200 + fetch http://localhost:3000 returns 200 Dev server running at http://localhost:3000 @@ -240,7 +240,7 @@ Plans execute autonomously. Checkpoints formalize interaction points where human Deploy to Vercel .vercel/, vercel.json Run `vercel --yes` to deploy - vercel ls shows deployment, curl returns 200 + vercel ls shows deployment, fetch returns 200 @@ -261,7 +261,7 @@ Plans execute autonomously. Checkpoints formalize interaction points where human Retry Vercel deployment Run `vercel --yes` (now authenticated) - vercel ls shows deployment, curl returns 200 + vercel ls shows deployment, fetch returns 200 ``` @@ -455,8 +455,8 @@ I'll verify: vercel whoami returns your account npm run dev & DEV_SERVER_PID=$! -# Wait for ready (max 30s) -timeout 30 bash -c 'until curl -s localhost:3000 > /dev/null 2>&1; do sleep 1; done' +# Wait for ready (max 30s) — uses fetch() for cross-platform compatibility +timeout 30 bash -c 'until node -e "fetch(\"http://localhost:3000\").then(r=>{process.exit(r.ok?0:1)}).catch(()=>process.exit(1))" 2>/dev/null; do sleep 1; done' ``` **Port conflicts:** Kill stale process (`lsof -ti:3000 | xargs kill`) or use alternate port (`--port 3001`). @@ -489,7 +489,9 @@ timeout 30 bash -c 'until curl -s localhost:3000 > /dev/null 2>&1; do sleep 1; d | Auth error | Create auth gate checkpoint | | Network timeout | Retry with backoff, then checkpoint if persistent | -**Never present a checkpoint with broken verification environment.** If `curl localhost:3000` fails, don't ask user to "visit localhost:3000". +**Never present a checkpoint with broken verification environment.** If the local server isn't responding, don't ask user to "visit localhost:3000". + +> **Cross-platform note:** Use `node -e "fetch('http://localhost:3000').then(r=>console.log(r.status))"` instead of `curl` for health checks. `curl` is broken on Windows MSYS/Git bash due to SSL/path mangling issues. ```xml @@ -502,7 +504,7 @@ timeout 30 bash -c 'until curl -s localhost:3000 > /dev/null 2>&1; do sleep 1; d Fix server startup issue Investigate error, fix root cause, restart server - curl http://localhost:3000 returns 200 + fetch http://localhost:3000 returns 200 @@ -608,7 +610,7 @@ timeout 30 bash -c 'until curl -s localhost:3000 > /dev/null 2>&1; do sleep 1; d Start dev server for auth testing Run `npm run dev` in background, wait for ready signal - curl http://localhost:3000 returns 200 + fetch http://localhost:3000 returns 200 Dev server running at http://localhost:3000 @@ -651,7 +653,7 @@ timeout 30 bash -c 'until curl -s localhost:3000 > /dev/null 2>&1; do sleep 1; d Start dev server Run `npm run dev` in background - curl localhost:3000 returns 200 + fetch http://localhost:3000 returns 200 @@ -677,7 +679,7 @@ timeout 30 bash -c 'until curl -s localhost:3000 > /dev/null 2>&1; do sleep 1; d Deploy to Vercel Run `vercel --yes`. Capture URL. - vercel ls shows deployment, curl returns 200 + vercel ls shows deployment, fetch returns 200 diff --git a/gsd-opencode/get-shit-done/references/decimal-phase-calculation.md b/gsd-opencode/get-shit-done/references/decimal-phase-calculation.md index f972693..fb34e09 100644 --- a/gsd-opencode/get-shit-done/references/decimal-phase-calculation.md +++ b/gsd-opencode/get-shit-done/references/decimal-phase-calculation.md @@ -32,9 +32,8 @@ With existing decimals: ## Extract Values ```bash -DECIMAL_INFO=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" phase next-decimal "${AFTER_PHASE}") -DECIMAL_PHASE=$(printf '%s\n' "$DECIMAL_INFO" | jq -r '.next') -BASE_PHASE=$(printf '%s\n' "$DECIMAL_INFO" | jq -r '.base_phase') +DECIMAL_PHASE=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" phase next-decimal "${AFTER_PHASE}" --pick next) +BASE_PHASE=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" phase next-decimal "${AFTER_PHASE}" --pick base_phase) ``` Or with --raw flag: diff --git a/gsd-opencode/get-shit-done/references/git-integration.md b/gsd-opencode/get-shit-done/references/git-integration.md index 8492919..771db08 100644 --- a/gsd-opencode/get-shit-done/references/git-integration.md +++ b/gsd-opencode/get-shit-done/references/git-integration.md @@ -61,6 +61,10 @@ node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: init Each task gets its own commit immediately after completion. +> **Parallel agents:** When running as a parallel executor (spawned by execute-phase), +> use `--no-verify` on all commits to avoid pre-commit hook lock contention. +> The orchestrator validates hooks once after all agents complete. + ``` {type}({phase}-{plan}): {task-name} @@ -246,3 +250,46 @@ Each plan produces 2-4 commits (tasks + metadata). Clear, granular, bisectable. - "Commit noise" irrelevant when consumer is OpenCode, not humans + + + +## Multi-Repo Workspace Support (sub_repos) + +For workspaces with separate git repos (e.g., `backend/`, `frontend/`, `shared/`), GSD routes commits to each repo independently. + +### Configuration + +In `.planning/config.json`, list sub-repo directories under `planning.sub_repos`: + +```json +{ + "planning": { + "commit_docs": false, + "sub_repos": ["backend", "frontend", "shared"] + } +} +``` + +Set `commit_docs: false` so planning docs stay local and are not committed to any sub-repo. + +### How It Works + +1. **Auto-detection:** During `/gsd-new-project`, directories with their own `.git` folder are detected and offered for selection as sub-repos. On subsequent runs, `loadConfig` auto-syncs the `sub_repos` list with the filesystem — adding newly created repos and removing deleted ones. This means `config.json` may be rewritten automatically when repos change on disk. +2. **File grouping:** Code files are grouped by their sub-repo prefix (e.g., `backend/src/api/users.ts` belongs to the `backend/` repo). +3. **Independent commits:** Each sub-repo receives its own atomic commit via `gsd-tools.cjs commit-to-subrepo`. File paths are made relative to the sub-repo root before staging. +4. **Planning stays local:** The `.planning/` directory is not committed; it acts as cross-repo coordination. + +### Commit Routing + +Instead of the standard `commit` command, use `commit-to-subrepo` when `sub_repos` is configured: + +```bash +node $HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit-to-subrepo "feat(02-01): add user API" \ + --files backend/src/api/users.ts backend/src/types/user.ts frontend/src/components/UserForm.tsx +``` + +This stages `src/api/users.ts` and `src/types/user.ts` in the `backend/` repo, and `src/components/UserForm.tsx` in the `frontend/` repo, then commits each independently with the same message. + +Files that don't match any configured sub-repo are reported as unmatched. + + diff --git a/gsd-opencode/get-shit-done/references/model-profile-resolution.md b/gsd-opencode/get-shit-done/references/model-profile-resolution.md index d82557b..ae0643e 100644 --- a/gsd-opencode/get-shit-done/references/model-profile-resolution.md +++ b/gsd-opencode/get-shit-done/references/model-profile-resolution.md @@ -26,6 +26,8 @@ task( **Note:** Opus-tier agents resolve to `"inherit"` (not `"opus"`). This causes the agent to use the parent session's model, avoiding conflicts with organization policies that may block specific opus versions. +If `model_profile` is `"inherit"`, all agents resolve to `"inherit"` (useful for OpenCode `/model`). + ## Usage 1. Resolve once at orchestration start diff --git a/gsd-opencode/get-shit-done/references/model-profiles.md b/gsd-opencode/get-shit-done/references/model-profiles.md index 12cccb2..b5d5dad 100644 --- a/gsd-opencode/get-shit-done/references/model-profiles.md +++ b/gsd-opencode/get-shit-done/references/model-profiles.md @@ -1,23 +1,23 @@ # Model Profiles -Model profiles control which OpenCode model each GSD agent uses. This allows balancing quality vs token spend. +Model profiles control which OpenCode model each GSD agent uses. This allows balancing quality vs token spend, or inheriting the currently selected session model. ## Profile Definitions -| Agent | `quality` | `balanced` | `budget` | -|-------|-----------|------------|----------| -| gsd-planner | opus | opus | sonnet | -| gsd-roadmapper | opus | sonnet | sonnet | -| gsd-executor | opus | sonnet | sonnet | -| gsd-phase-researcher | opus | sonnet | haiku | -| gsd-project-researcher | opus | sonnet | haiku | -| gsd-research-synthesizer | sonnet | sonnet | haiku | -| gsd-debugger | opus | sonnet | sonnet | -| gsd-codebase-mapper | sonnet | haiku | haiku | -| gsd-verifier | sonnet | sonnet | haiku | -| gsd-plan-checker | sonnet | sonnet | haiku | -| gsd-integration-checker | sonnet | sonnet | haiku | -| gsd-nyquist-auditor | sonnet | sonnet | haiku | +| Agent | `quality` | `balanced` | `budget` | `inherit` | +|-------|-----------|------------|----------|-----------| +| gsd-planner | opus | opus | sonnet | inherit | +| gsd-roadmapper | opus | sonnet | sonnet | inherit | +| gsd-executor | opus | sonnet | sonnet | inherit | +| gsd-phase-researcher | opus | sonnet | haiku | inherit | +| gsd-project-researcher | opus | sonnet | haiku | inherit | +| gsd-research-synthesizer | sonnet | sonnet | haiku | inherit | +| gsd-debugger | opus | sonnet | sonnet | inherit | +| gsd-codebase-mapper | sonnet | haiku | haiku | inherit | +| gsd-verifier | sonnet | sonnet | haiku | inherit | +| gsd-plan-checker | sonnet | sonnet | haiku | inherit | +| gsd-integration-checker | sonnet | sonnet | haiku | inherit | +| gsd-nyquist-auditor | sonnet | sonnet | haiku | inherit | ## Profile Philosophy @@ -37,6 +37,49 @@ Model profiles control which OpenCode model each GSD agent uses. This allows bal - Haiku for research and verification - Use when: conserving quota, high-volume work, less critical phases +**inherit** - Follow the current session model +- All agents resolve to `inherit` +- Best when you switch models interactively (for example OpenCode `/model`) +- **Required when using non-Anthropic providers** (OpenRouter, local models, etc.) — otherwise GSD may call Anthropic models directly, incurring unexpected costs +- Use when: you want GSD to follow your currently selected runtime model + +## Using Non-OpenCode Runtimes (Codex, OpenCode, Gemini CLI) + +When installed for a non-OpenCode runtime, the GSD installer sets `resolve_model_ids: "omit"` in `~/.gsd/defaults.json`. This returns an empty model parameter for all agents, so each agent uses the runtime's default model. No manual setup is needed. + +To assign different models to different agents, add `model_overrides` with model IDs your runtime recognizes: + +```json +{ + "resolve_model_ids": "omit", + "model_overrides": { + "gsd-planner": "o3", + "gsd-executor": "o4-mini", + "gsd-debugger": "o3", + "gsd-codebase-mapper": "o4-mini" + } +} +``` + +The same tiering logic applies: stronger models for planning and debugging, cheaper models for execution and mapping. + +## Using OpenCode with Non-Anthropic Providers (OpenRouter, Local) + +If you're using OpenCode with OpenRouter, a local model, or any non-Anthropic provider, set the `inherit` profile to prevent GSD from calling Anthropic models for subagents: + +```bash +# Via settings command +/gsd-settings +# → Select "Inherit" for model profile + +# Or manually in .planning/config.json +{ + "model_profile": "inherit" +} +``` + +Without `inherit`, GSD's default `balanced` profile spawns specific Anthropic models (`opus`, `sonnet`, `haiku`) for each agent type, which can result in additional API costs through your non-Anthropic provider. + ## Resolution Logic Orchestrators resolve model before spawning: @@ -62,7 +105,7 @@ Override specific agents without changing the entire profile: } ``` -Overrides take precedence over the profile. Valid values: `opus`, `sonnet`, `haiku`. +Overrides take precedence over the profile. Valid values: `opus`, `sonnet`, `haiku`, `inherit`, or any fully-qualified model ID (e.g., `"o3"`, `"openai/o3"`, `"google/gemini-2.5-pro"`). ## Switching Profiles @@ -91,3 +134,6 @@ read-only exploration and pattern extraction. No reasoning required, just struct **Why `inherit` instead of passing `opus` directly?** OpenCode's `"opus"` alias maps to a specific model version. Organizations may block older opus versions while allowing newer ones. GSD returns `"inherit"` for opus-tier agents, causing them to use whatever opus version the user has configured in their session. This avoids version conflicts and silent fallbacks to Sonnet. + +**Why `inherit` profile?** +Some runtimes (including OpenCode) let users switch models at runtime (`/model`). The `inherit` profile keeps all GSD subagents aligned to that live selection. diff --git a/gsd-opencode/get-shit-done/references/phase-argument-parsing.md b/gsd-opencode/get-shit-done/references/phase-argument-parsing.md index 2762c58..0e4e779 100644 --- a/gsd-opencode/get-shit-done/references/phase-argument-parsing.md +++ b/gsd-opencode/get-shit-done/references/phase-argument-parsing.md @@ -45,8 +45,8 @@ fi Use `roadmap get-phase` to validate phase exists: ```bash -PHASE_CHECK=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "${PHASE}") -if [ "$(printf '%s\n' "$PHASE_CHECK" | jq -r '.found')" = "false" ]; then +PHASE_CHECK=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "${PHASE}" --pick found) +if [ "$PHASE_CHECK" = "false" ]; then echo "ERROR: Phase ${PHASE} not found in roadmap" exit 1 fi diff --git a/gsd-opencode/get-shit-done/references/planning-config.md b/gsd-opencode/get-shit-done/references/planning-config.md index 842cfd8..ea8af9b 100644 --- a/gsd-opencode/get-shit-done/references/planning-config.md +++ b/gsd-opencode/get-shit-done/references/planning-config.md @@ -11,7 +11,8 @@ Configuration options for `.planning/` directory behavior. "git": { "branching_strategy": "none", "phase_branch_template": "gsd/phase-{phase}-{slug}", - "milestone_branch_template": "gsd/{milestone}-{slug}" + "milestone_branch_template": "gsd/{milestone}-{slug}", + "quick_branch_template": null } ``` @@ -22,6 +23,7 @@ Configuration options for `.planning/` directory behavior. | `git.branching_strategy` | `"none"` | Git branching approach: `"none"`, `"phase"`, or `"milestone"` | | `git.phase_branch_template` | `"gsd/phase-{phase}-{slug}"` | Branch template for phase strategy | | `git.milestone_branch_template` | `"gsd/{milestone}-{slug}"` | Branch template for milestone strategy | +| `git.quick_branch_template` | `null` | Optional branch template for quick-task runs | diff --git a/gsd-opencode/get-shit-done/references/user-profiling.md b/gsd-opencode/get-shit-done/references/user-profiling.md new file mode 100644 index 0000000..d390dc9 --- /dev/null +++ b/gsd-opencode/get-shit-done/references/user-profiling.md @@ -0,0 +1,681 @@ +# User Profiling: Detection Heuristics Reference + +This reference document defines detection heuristics for behavioral profiling across 8 dimensions. The gsd-user-profiler agent applies these rules when analyzing extracted session messages. Do not invent dimensions or scoring rules beyond what is defined here. + +## How to Use This Document + +1. The gsd-user-profiler agent reads this document before analyzing any messages +2. For each dimension, the agent scans messages for the signal patterns defined below +3. The agent applies the detection heuristics to classify the developer's pattern +4. Confidence is scored using the thresholds defined per dimension +5. Evidence quotes are curated using the rules in the Evidence Curation section +6. Output must conform to the JSON schema in the Output Schema section + +--- + +## Dimensions + +### 1. Communication Style + +`dimension_id: communication_style` + +**What we're measuring:** How the developer phrases requests, instructions, and feedback -- the structural pattern of their messages to OpenCode. + +**Rating spectrum:** + +| Rating | Description | +|--------|-------------| +| `terse-direct` | Short, imperative messages with minimal context. Gets to the point immediately. | +| `conversational` | Medium-length messages mixing instructions with questions and thinking-aloud. Natural, informal tone. | +| `detailed-structured` | Long messages with explicit structure -- headers, numbered lists, problem statements, pre-analysis. | +| `mixed` | No dominant pattern; style shifts based on task type or project context. | + +**Signal patterns:** + +1. **Message length distribution** -- Average word count across messages. Terse < 50 words, conversational 50-200 words, detailed > 200 words. +2. **Imperative-to-interrogative ratio** -- Ratio of commands ("fix this", "add X") to questions ("what do you think?", "should we?"). High imperative ratio suggests terse-direct. +3. **Structural formatting** -- Presence of markdown headers, numbered lists, code blocks, or bullet points within messages. Frequent formatting suggests detailed-structured. +4. **Context preambles** -- Whether the developer provides background/context before making a request. Preambles suggest conversational or detailed-structured. +5. **Sentence completeness** -- Whether messages use full sentences or fragments/shorthand. Fragments suggest terse-direct. +6. **Follow-up pattern** -- Whether the developer provides additional context in subsequent messages (multi-message requests suggest conversational). + +**Detection heuristics:** + +1. If average message length < 50 words AND predominantly imperative mood AND minimal formatting --> `terse-direct` +2. If average message length 50-200 words AND mix of imperative and interrogative AND occasional formatting --> `conversational` +3. If average message length > 200 words AND frequent structural formatting AND context preambles present --> `detailed-structured` +4. If message length variance is high (std dev > 60% of mean) AND no single pattern dominates (< 60% of messages match one style) --> `mixed` +5. If pattern varies systematically by project type (e.g., terse in CLI projects, detailed in frontend) --> `mixed` with context-dependent note + +**Confidence scoring:** + +- **HIGH:** 10+ messages showing consistent pattern (> 70% match), same pattern observed across 2+ projects +- **MEDIUM:** 5-9 messages showing pattern, OR pattern consistent within 1 project only +- **LOW:** < 5 messages with relevant signals, OR mixed signals (contradictory patterns observed in similar contexts) +- **UNSCORED:** 0 messages with relevant signals for this dimension + +**Example quotes:** + +- **terse-direct:** "fix the auth bug" / "add pagination to the list endpoint" / "this test is failing, make it pass" +- **conversational:** "I'm thinking we should probably handle the error case here. What do you think about returning a 422 instead of a 500? The client needs to know it was a validation issue." +- **detailed-structured:** "## Context\nThe auth flow currently uses session cookies but we need to migrate to JWT.\n\n## Requirements\n1. Access tokens (15min expiry)\n2. Refresh tokens (7-day)\n3. httpOnly cookies\n\n## What I've tried\nI looked at jose and jsonwebtoken..." + +**Context-dependent patterns:** + +When communication style varies systematically by project or task type, report the split rather than forcing a single rating. Example: "context-dependent: terse-direct for bug fixes and CLI tooling, detailed-structured for architecture and frontend work." Phase 3 orchestration resolves context-dependent splits by presenting the split to the user. + +--- + +### 2. Decision Speed + +`dimension_id: decision_speed` + +**What we're measuring:** How quickly the developer makes choices when OpenCode presents options, alternatives, or trade-offs. + +**Rating spectrum:** + +| Rating | Description | +|--------|-------------| +| `fast-intuitive` | Decides immediately based on experience or gut feeling. Minimal deliberation. | +| `deliberate-informed` | Requests comparison or summary before deciding. Wants to understand trade-offs. | +| `research-first` | Delays decision to research independently. May leave and return with findings. | +| `delegator` | Defers to OpenCode's recommendation. Trusts the suggestion. | + +**Signal patterns:** + +1. **Response latency to options** -- How many messages between OpenCode presenting options and developer choosing. Immediate (same message or next) suggests fast-intuitive. +2. **Comparison requests** -- Presence of "compare these", "what are the trade-offs?", "pros and cons?" suggests deliberate-informed. +3. **External research indicators** -- Messages like "I looked into X and...", "according to the docs...", "I read that..." suggest research-first. +4. **Delegation language** -- "just pick one", "whatever you recommend", "your call", "go with the best option" suggests delegator. +5. **Decision reversal frequency** -- How often the developer changes a decision after making it. Frequent reversals may indicate fast-intuitive with low confidence. + +**Detection heuristics:** + +1. If developer selects options within 1-2 messages of presentation AND uses decisive language ("use X", "go with A") AND rarely asks for comparisons --> `fast-intuitive` +2. If developer requests trade-off analysis or comparison tables AND decides after receiving comparison AND asks clarifying questions --> `deliberate-informed` +3. If developer defers decisions with "let me look into this" AND returns with external information AND cites documentation or articles --> `research-first` +4. If developer uses delegation language (> 3 instances) AND rarely overrides OpenCode's choices AND says "sounds good" or "your call" --> `delegator` +5. If no clear pattern OR evidence is split across multiple styles --> classify as the dominant style with a context-dependent note + +**Confidence scoring:** + +- **HIGH:** 10+ decision points observed showing consistent pattern, same pattern across 2+ projects +- **MEDIUM:** 5-9 decision points, OR consistent within 1 project only +- **LOW:** < 5 decision points observed, OR mixed decision-making styles +- **UNSCORED:** 0 messages containing decision-relevant signals + +**Example quotes:** + +- **fast-intuitive:** "Use Tailwind. Next question." / "Option B, let's move on" +- **deliberate-informed:** "Can you compare Prisma vs Drizzle for this use case? I want to understand the migration story and type safety differences before I pick." +- **research-first:** "Hold off on the DB choice -- I want to read the Drizzle docs and check their GitHub issues first. I'll come back with a decision." +- **delegator:** "You know more about this than me. Whatever you recommend, go with it." + +**Context-dependent patterns:** + +Decision speed often varies by stakes. A developer may be fast-intuitive for styling choices but research-first for database or auth decisions. When this pattern is clear, report the split: "context-dependent: fast-intuitive for low-stakes (styling, naming), deliberate-informed for high-stakes (architecture, security)." + +--- + +### 3. Explanation Depth + +`dimension_id: explanation_depth` + +**What we're measuring:** How much explanation the developer wants alongside code -- their preference for understanding vs. speed. + +**Rating spectrum:** + +| Rating | Description | +|--------|-------------| +| `code-only` | Wants working code with minimal or no explanation. Reads and understands code directly. | +| `concise` | Wants brief explanation of approach with code. Key decisions noted, not exhaustive. | +| `detailed` | Wants thorough walkthrough of the approach, reasoning, and code. Appreciates structure. | +| `educational` | Wants deep conceptual explanation. Treats interactions as learning opportunities. | + +**Signal patterns:** + +1. **Explicit depth requests** -- "just show me the code", "explain why", "teach me about X", "skip the explanation" +2. **Reaction to explanations** -- Does the developer skip past explanations? Ask for more detail? Say "too much"? +3. **Follow-up question depth** -- Surface-level follow-ups ("does it work?") vs. conceptual ("why this pattern over X?") +4. **Code comprehension signals** -- Does the developer reference implementation details in their messages? This suggests they read and understand code directly. +5. **"I know this" signals** -- Messages like "I'm familiar with X", "skip the basics", "I know how hooks work" indicate lower explanation preference. + +**Detection heuristics:** + +1. If developer says "just the code" or "skip the explanation" AND rarely asks follow-up conceptual questions AND references code details directly --> `code-only` +2. If developer accepts brief explanations without asking for more AND asks focused follow-ups about specific decisions --> `concise` +3. If developer asks "why" questions AND requests walkthroughs AND appreciates structured explanations --> `detailed` +4. If developer asks conceptual questions beyond the immediate task AND uses learning language ("I want to understand", "teach me") --> `educational` + +**Confidence scoring:** + +- **HIGH:** 10+ messages showing consistent preference, same preference across 2+ projects +- **MEDIUM:** 5-9 messages, OR consistent within 1 project only +- **LOW:** < 5 relevant messages, OR preferences shift between interactions +- **UNSCORED:** 0 messages with relevant signals + +**Example quotes:** + +- **code-only:** "Just give me the implementation. I'll read through it." / "Skip the explanation, show the code." +- **concise:** "Quick summary of the approach, then the code please." / "Why did you use a Map here instead of an object?" +- **detailed:** "Walk me through this step by step. I want to understand the auth flow before we implement it." +- **educational:** "Can you explain how JWT refresh token rotation works conceptually? I want to understand the security model, not just implement it." + +**Context-dependent patterns:** + +Explanation depth often correlates with domain familiarity. A developer may want code-only for well-known tech but educational for new domains. Report splits when observed: "context-dependent: code-only for React/TypeScript, detailed for database optimization." + +--- + +### 4. Debugging Approach + +`dimension_id: debugging_approach` + +**What we're measuring:** How the developer approaches problems, errors, and unexpected behavior when working with OpenCode. + +**Rating spectrum:** + +| Rating | Description | +|--------|-------------| +| `fix-first` | Pastes error, wants it fixed. Minimal diagnosis interest. Results-oriented. | +| `diagnostic` | Shares error with context, wants to understand the cause before fixing. | +| `hypothesis-driven` | Investigates independently first, brings specific theories to OpenCode for validation. | +| `collaborative` | Wants to work through the problem step-by-step with OpenCode as a partner. | + +**Signal patterns:** + +1. **Error presentation style** -- Raw error paste only (fix-first) vs. error + "I think it might be..." (hypothesis-driven) vs. "Can you help me understand why..." (diagnostic) +2. **Pre-investigation indicators** -- Does the developer share what they already tried? Do they mention reading logs, checking state, or isolating the issue? +3. **Root cause interest** -- After a fix, does the developer ask "why did that happen?" or just move on? +4. **Step-by-step language** -- "Let's check X first", "what should we look at next?", "walk me through the debugging" +5. **Fix acceptance pattern** -- Does the developer immediately apply fixes or question them first? + +**Detection heuristics:** + +1. If developer pastes errors without context AND accepts fixes without root cause questions AND moves on immediately --> `fix-first` +2. If developer provides error context AND asks "why is this happening?" AND wants explanation with the fix --> `diagnostic` +3. If developer shares their own analysis AND proposes theories ("I think the issue is X because...") AND asks OpenCode to confirm or refute --> `hypothesis-driven` +4. If developer uses collaborative language ("let's", "what should we check?") AND prefers incremental diagnosis AND walks through problems together --> `collaborative` + +**Confidence scoring:** + +- **HIGH:** 10+ debugging interactions showing consistent approach, same approach across 2+ projects +- **MEDIUM:** 5-9 debugging interactions, OR consistent within 1 project only +- **LOW:** < 5 debugging interactions, OR approach varies significantly +- **UNSCORED:** 0 messages with debugging-relevant signals + +**Example quotes:** + +- **fix-first:** "Getting this error: TypeError: Cannot read properties of undefined. Fix it." +- **diagnostic:** "The API returns 500 when I send a POST to /users. Here's the request body and the server log. What's causing this?" +- **hypothesis-driven:** "I think the race condition is in the useEffect cleanup. I checked and the subscription isn't being cancelled on unmount. Can you confirm?" +- **collaborative:** "Let's debug this together. The test passes locally but fails in CI. What should we check first?" + +**Context-dependent patterns:** + +Debugging approach may vary by urgency. A developer might be fix-first under deadline pressure but hypothesis-driven during regular development. Note temporal patterns if detected. + +--- + +### 5. UX Philosophy + +`dimension_id: ux_philosophy` + +**What we're measuring:** How the developer prioritizes user experience, design, and visual quality relative to functionality. + +**Rating spectrum:** + +| Rating | Description | +|--------|-------------| +| `function-first` | Get it working, polish later. Minimal UX concern during implementation. | +| `pragmatic` | Basic usability from the start. Nothing ugly or broken, but no design obsession. | +| `design-conscious` | Design and UX are treated as important as functionality. Attention to visual detail. | +| `backend-focused` | Primarily builds backend/CLI. Minimal frontend exposure or interest. | + +**Signal patterns:** + +1. **Design-related requests** -- Mentions of styling, layout, responsiveness, animations, color schemes, spacing +2. **Polish timing** -- Does the developer ask for visual polish during implementation or defer it? +3. **UI feedback specificity** -- Vague ("make it look better") vs. specific ("increase the padding to 16px, change the font weight to 600") +4. **Frontend vs. backend distribution** -- Ratio of frontend-focused requests to backend-focused requests +5. **Accessibility mentions** -- References to a11y, screen readers, keyboard navigation, ARIA labels + +**Detection heuristics:** + +1. If developer rarely mentions UI/UX AND focuses on logic, APIs, data AND defers styling ("we'll make it pretty later") --> `function-first` +2. If developer includes basic UX requirements AND mentions usability but not pixel-perfection AND balances form with function --> `pragmatic` +3. If developer provides specific design requirements AND mentions polish, animations, spacing AND treats UI bugs as seriously as logic bugs --> `design-conscious` +4. If developer works primarily on CLI tools, APIs, or backend systems AND rarely or never works on frontend AND messages focus on data, performance, infrastructure --> `backend-focused` + +**Confidence scoring:** + +- **HIGH:** 10+ messages with UX-relevant signals, same pattern across 2+ projects +- **MEDIUM:** 5-9 messages, OR consistent within 1 project only +- **LOW:** < 5 relevant messages, OR philosophy varies by project type +- **UNSCORED:** 0 messages with UX-relevant signals + +**Example quotes:** + +- **function-first:** "Just get the form working. We'll style it later." / "I don't care how it looks, I need the data flowing." +- **pragmatic:** "Make sure the loading state is visible and the error messages are clear. Standard styling is fine." +- **design-conscious:** "The button needs more breathing room -- add 12px vertical padding and make the hover state transition 200ms. Also check the contrast ratio." +- **backend-focused:** "I'm building a CLI tool. No UI needed." / "Add the REST endpoint, I'll handle the frontend separately." + +**Context-dependent patterns:** + +UX philosophy is inherently project-dependent. A developer building a CLI tool is necessarily backend-focused for that project. When possible, distinguish between project-driven and preference-driven patterns. If the developer only has backend projects, note that the rating reflects available data: "backend-focused (note: all analyzed projects are backend/CLI -- may not reflect frontend preferences)." + +--- + +### 6. Vendor Philosophy + +`dimension_id: vendor_philosophy` + +**What we're measuring:** How the developer approaches choosing and evaluating libraries, frameworks, and external services. + +**Rating spectrum:** + +| Rating | Description | +|--------|-------------| +| `pragmatic-fast` | Uses what works, what OpenCode suggests, or what's fastest. Minimal evaluation. | +| `conservative` | Prefers well-known, battle-tested, widely-adopted options. Risk-averse. | +| `thorough-evaluator` | Researches alternatives, reads docs, compares features and trade-offs before committing. | +| `opinionated` | Has strong, pre-existing preferences for specific tools. Knows what they like. | + +**Signal patterns:** + +1. **Library selection language** -- "just use whatever", "is X the standard?", "I want to compare A vs B", "we're using X, period" +2. **Evaluation depth** -- Does the developer accept the first suggestion or ask for alternatives? +3. **Stated preferences** -- Explicit mentions of preferred tools, past experience, or tool philosophy +4. **Rejection patterns** -- Does the developer reject OpenCode's suggestions? On what basis (popularity, personal experience, docs quality)? +5. **Dependency attitude** -- "minimize dependencies", "no external deps", "add whatever we need" -- reveals philosophy about external code + +**Detection heuristics:** + +1. If developer accepts library suggestions without pushback AND uses phrases like "sounds good" or "go with that" AND rarely asks about alternatives --> `pragmatic-fast` +2. If developer asks about popularity, maintenance, community AND prefers "industry standard" or "battle-tested" AND avoids new/experimental --> `conservative` +3. If developer requests comparisons AND reads docs before deciding AND asks about edge cases, license, bundle size --> `thorough-evaluator` +4. If developer names specific libraries unprompted AND overrides OpenCode's suggestions AND expresses strong preferences --> `opinionated` + +**Confidence scoring:** + +- **HIGH:** 10+ vendor/library decisions observed, same pattern across 2+ projects +- **MEDIUM:** 5-9 decisions, OR consistent within 1 project only +- **LOW:** < 5 vendor decisions observed, OR pattern varies +- **UNSCORED:** 0 messages with vendor-selection signals + +**Example quotes:** + +- **pragmatic-fast:** "Use whatever ORM you recommend. I just need it working." / "Sure, Tailwind is fine." +- **conservative:** "Is Prisma the most widely used ORM for this? I want something with a large community." / "Let's stick with what most teams use." +- **thorough-evaluator:** "Before we pick a state management library, can you compare Zustand vs Jotai vs Redux Toolkit? I want to understand bundle size, API surface, and TypeScript support." +- **opinionated:** "We're using Drizzle, not Prisma. I've used both and Drizzle's SQL-like API is better for complex queries." + +**Context-dependent patterns:** + +Vendor philosophy may shift based on project importance or domain. Personal projects may use pragmatic-fast while professional projects use thorough-evaluator. Report the split if detected. + +--- + +### 7. Frustration Triggers + +`dimension_id: frustration_triggers` + +**What we're measuring:** What causes visible frustration, correction, or negative emotional signals in the developer's messages to OpenCode. + +**Rating spectrum:** + +| Rating | Description | +|--------|-------------| +| `scope-creep` | Frustrated when OpenCode does things that were not asked for. Wants bounded execution. | +| `instruction-adherence` | Frustrated when OpenCode doesn't follow instructions precisely. Values exactness. | +| `verbosity` | Frustrated when OpenCode over-explains or is too wordy. Wants conciseness. | +| `regression` | Frustrated when OpenCode breaks working code while fixing something else. Values stability. | + +**Signal patterns:** + +1. **Correction language** -- "I didn't ask for that", "don't do X", "I said Y not Z", "why did you change this?" +2. **Repetition patterns** -- Repeating the same instruction with emphasis suggests instruction-adherence frustration +3. **Emotional tone shifts** -- Shift from neutral to terse, use of capitals, exclamation marks, explicit frustration words +4. **"Don't" statements** -- "don't add extra features", "don't explain so much", "don't touch that file" -- what they prohibit reveals what frustrates them +5. **Frustration recovery** -- How quickly the developer returns to neutral tone after a frustration event + +**Detection heuristics:** + +1. If developer corrects OpenCode for doing unrequested work AND uses language like "I only asked for X", "stop adding things", "stick to what I asked" --> `scope-creep` +2. If developer repeats instructions AND corrects specific deviations from stated requirements AND emphasizes precision ("I specifically said...") --> `instruction-adherence` +3. If developer asks OpenCode to be shorter AND skips explanations AND expresses annoyance at length ("too much", "just the answer") --> `verbosity` +4. If developer expresses frustration at broken functionality AND checks for regressions AND says "you broke X while fixing Y" --> `regression` + +**Confidence scoring:** + +- **HIGH:** 10+ frustration events showing consistent trigger pattern, same trigger across 2+ projects +- **MEDIUM:** 5-9 frustration events, OR consistent within 1 project only +- **LOW:** < 5 frustration events observed (note: low frustration count is POSITIVE -- it means the developer is generally satisfied, not that data is insufficient) +- **UNSCORED:** 0 messages with frustration signals (note: "no frustration detected" is a valid finding) + +**Example quotes:** + +- **scope-creep:** "I asked you to fix the login bug, not refactor the entire auth module. Revert everything except the bug fix." +- **instruction-adherence:** "I said to use a Map, not an object. I was specific about this. Please redo it with a Map." +- **verbosity:** "Way too much explanation. Just show me the code change, nothing else." +- **regression:** "The search was working fine before. Now after your 'fix' to the filter, search results are empty. Don't touch things I didn't ask you to change." + +**Context-dependent patterns:** + +Frustration triggers tend to be consistent across projects (personality-driven, not project-driven). However, their intensity may vary with project stakes. If multiple frustration triggers are observed, report the primary (most frequent) and note secondaries. + +--- + +### 8. Learning Style + +`dimension_id: learning_style` + +**What we're measuring:** How the developer prefers to understand new concepts, tools, or patterns they encounter. + +**Rating spectrum:** + +| Rating | Description | +|--------|-------------| +| `self-directed` | Reads code directly, figures things out independently. Asks OpenCode specific questions. | +| `guided` | Asks OpenCode to explain relevant parts. Prefers guided understanding. | +| `documentation-first` | Reads official docs and tutorials before diving in. References documentation. | +| `example-driven` | Wants working examples to modify and learn from. Pattern-matching learner. | + +**Signal patterns:** + +1. **Learning initiation** -- Does the developer start by reading code, asking for explanation, requesting docs, or asking for examples? +2. **Reference to external sources** -- Mentions of documentation, tutorials, Stack Overflow, blog posts suggest documentation-first +3. **Example requests** -- "show me an example", "can you give me a sample?", "let me see how this looks in practice" +4. **Code-reading indicators** -- "I looked at the implementation", "I see that X calls Y", "from reading the code..." +5. **Explanation requests vs. code requests** -- Ratio of "explain X" to "show me X" messages + +**Detection heuristics:** + +1. If developer references reading code directly AND asks specific targeted questions AND demonstrates independent investigation --> `self-directed` +2. If developer asks OpenCode to explain concepts AND requests walkthroughs AND prefers OpenCode-mediated understanding --> `guided` +3. If developer cites documentation AND asks for doc links AND mentions reading tutorials or official guides --> `documentation-first` +4. If developer requests examples AND modifies provided examples AND learns by pattern matching --> `example-driven` + +**Confidence scoring:** + +- **HIGH:** 10+ learning interactions showing consistent preference, same preference across 2+ projects +- **MEDIUM:** 5-9 learning interactions, OR consistent within 1 project only +- **LOW:** < 5 learning interactions, OR preference varies by topic familiarity +- **UNSCORED:** 0 messages with learning-relevant signals + +**Example quotes:** + +- **self-directed:** "I read through the middleware code. The issue is that the token check happens after the rate limiter. Should those be swapped?" +- **guided:** "Can you walk me through how the auth flow works in this codebase? Start from the login request." +- **documentation-first:** "I read the Prisma docs on relations. Can you help me apply the many-to-many pattern from their guide to our schema?" +- **example-driven:** "Show me a working example of a protected API route with JWT validation. I'll adapt it for our endpoints." + +**Context-dependent patterns:** + +Learning style often varies with domain expertise. A developer may be self-directed in familiar domains but guided or example-driven in new ones. Report the split if detected: "context-dependent: self-directed for TypeScript/Node, example-driven for Rust/systems programming." + +--- + +## Evidence Curation + +### Evidence Format + +Use the combined format for each evidence entry: + +**Signal:** [pattern interpretation -- what the quote demonstrates] / **Example:** "[trimmed quote, ~100 characters]" -- project: [project name] + +### Evidence Targets + +- **3 evidence quotes per dimension** (24 total across all 8 dimensions) +- Select quotes that best illustrate the rated pattern +- Prefer quotes from different projects to demonstrate cross-project consistency +- When fewer than 3 relevant quotes exist, include what is available and note the evidence count + +### Quote Truncation + +- Trim quotes to the behavioral signal -- the part that demonstrates the pattern +- Target approximately 100 characters per quote +- Preserve the meaningful fragment, not the full message +- If the signal is in the middle of a long message, use "..." to indicate trimming +- Never include the full 500-character message when 50 characters capture the signal + +### Project Attribution + +- Every evidence quote must include the project name +- Project attribution enables verification and shows cross-project patterns +- Format: `-- project: [name]` + +### Sensitive Content Exclusion (Layer 1) + +The profiler agent must never select quotes containing any of the following patterns: + +- `sk-` (API key prefixes) +- `Bearer ` (auth tokens) +- `password` (credentials) +- `secret` (secrets) +- `token` (when used as a credential value, not a concept discussion) +- `api_key` or `API_KEY` (API key references) +- Full absolute file paths containing usernames (e.g., `/Users/john/...`, `/home/john/...`) + +**When sensitive content is found and excluded**, report as metadata in the analysis output: + +```json +{ + "sensitive_excluded": [ + { "type": "api_key_pattern", "count": 2 }, + { "type": "file_path_with_username", "count": 1 } + ] +} +``` + +This metadata enables defense-in-depth auditing. Layer 2 (regex filter in the write-profile step) provides a second pass, but the profiler should still avoid selecting sensitive quotes. + +### Natural Language Priority + +Weight natural language messages higher than: +- Pasted log output (detected by timestamps, repeated format strings, `[DEBUG]`, `[INFO]`, `[ERROR]`) +- Session context dumps (messages starting with "This session is being continued from a previous conversation") +- Large code pastes (messages where > 80% of content is inside code fences) + +These message types are genuine but carry less behavioral signal. Deprioritize them when selecting evidence quotes. + +--- + +## Recency Weighting + +### Guideline + +Recent sessions (last 30 days) should be weighted approximately 3x compared to older sessions when analyzing patterns. + +### Rationale + +Developer styles evolve. A developer who was terse six months ago may now provide detailed structured context. Recent behavior is a more accurate reflection of current working style. + +### Application + +1. When counting signals for confidence scoring, recent signals count 3x (e.g., 4 recent signals = 12 weighted signals) +2. When selecting evidence quotes, prefer recent quotes over older ones when both demonstrate the same pattern +3. When patterns conflict between recent and older sessions, the recent pattern takes precedence for the rating, but note the evolution: "recently shifted from terse-direct to conversational" +4. The 30-day window is relative to the analysis date, not a fixed date + +### Edge Cases + +- If ALL sessions are older than 30 days, apply no weighting (all sessions are equally stale) +- If ALL sessions are within the last 30 days, apply no weighting (all sessions are equally recent) +- The 3x weight is a guideline, not a hard multiplier -- use judgment when the weighted count changes a confidence threshold + +--- + +## Thin Data Handling + +### Message Thresholds + +| Total Genuine Messages | Mode | Behavior | +|------------------------|------|----------| +| > 50 | `full` | Full analysis across all 8 dimensions. Questionnaire optional (user can choose to supplement). | +| 20-50 | `hybrid` | Analyze available messages. Score each dimension with confidence. Supplement with questionnaire for LOW/UNSCORED dimensions. | +| < 20 | `insufficient` | All dimensions scored LOW or UNSCORED. Recommend questionnaire fallback as primary profile source. Note: "insufficient session data for behavioral analysis." | + +### Handling Insufficient Dimensions + +When a specific dimension has insufficient data (even if total messages exceed thresholds): + +- Set confidence to `UNSCORED` +- Set summary to: "Insufficient data -- no clear signals detected for this dimension." +- Set claude_instruction to a neutral fallback: "No strong preference detected. Ask the developer when this dimension is relevant." +- Set evidence_quotes to empty array `[]` +- Set evidence_count to `0` + +### Questionnaire Supplement + +When operating in `hybrid` mode, the questionnaire fills gaps for dimensions where session analysis produced LOW or UNSCORED confidence. The questionnaire-derived ratings use: +- **MEDIUM** confidence for strong, definitive picks +- **LOW** confidence for "it varies" or ambiguous selections + +If session analysis and questionnaire agree on a dimension, confidence can be elevated (e.g., session LOW + questionnaire MEDIUM agreement = MEDIUM). + +--- + +## Output Schema + +The profiler agent must return JSON matching this exact schema, wrapped in `` tags. + +```json +{ + "profile_version": "1.0", + "analyzed_at": "ISO-8601 timestamp", + "data_source": "session_analysis", + "projects_analyzed": ["project-name-1", "project-name-2"], + "messages_analyzed": 0, + "message_threshold": "full|hybrid|insufficient", + "sensitive_excluded": [ + { "type": "string", "count": 0 } + ], + "dimensions": { + "communication_style": { + "rating": "terse-direct|conversational|detailed-structured|mixed", + "confidence": "HIGH|MEDIUM|LOW|UNSCORED", + "evidence_count": 0, + "cross_project_consistent": true, + "evidence_quotes": [ + { + "signal": "Pattern interpretation describing what the quote demonstrates", + "quote": "Trimmed quote, approximately 100 characters", + "project": "project-name" + } + ], + "summary": "One to two sentence description of the observed pattern", + "claude_instruction": "Imperative directive for OpenCode: 'Match structured communication style' not 'You tend to provide structured context'" + }, + "decision_speed": { + "rating": "fast-intuitive|deliberate-informed|research-first|delegator", + "confidence": "HIGH|MEDIUM|LOW|UNSCORED", + "evidence_count": 0, + "cross_project_consistent": true, + "evidence_quotes": [], + "summary": "string", + "claude_instruction": "string" + }, + "explanation_depth": { + "rating": "code-only|concise|detailed|educational", + "confidence": "HIGH|MEDIUM|LOW|UNSCORED", + "evidence_count": 0, + "cross_project_consistent": true, + "evidence_quotes": [], + "summary": "string", + "claude_instruction": "string" + }, + "debugging_approach": { + "rating": "fix-first|diagnostic|hypothesis-driven|collaborative", + "confidence": "HIGH|MEDIUM|LOW|UNSCORED", + "evidence_count": 0, + "cross_project_consistent": true, + "evidence_quotes": [], + "summary": "string", + "claude_instruction": "string" + }, + "ux_philosophy": { + "rating": "function-first|pragmatic|design-conscious|backend-focused", + "confidence": "HIGH|MEDIUM|LOW|UNSCORED", + "evidence_count": 0, + "cross_project_consistent": true, + "evidence_quotes": [], + "summary": "string", + "claude_instruction": "string" + }, + "vendor_philosophy": { + "rating": "pragmatic-fast|conservative|thorough-evaluator|opinionated", + "confidence": "HIGH|MEDIUM|LOW|UNSCORED", + "evidence_count": 0, + "cross_project_consistent": true, + "evidence_quotes": [], + "summary": "string", + "claude_instruction": "string" + }, + "frustration_triggers": { + "rating": "scope-creep|instruction-adherence|verbosity|regression", + "confidence": "HIGH|MEDIUM|LOW|UNSCORED", + "evidence_count": 0, + "cross_project_consistent": true, + "evidence_quotes": [], + "summary": "string", + "claude_instruction": "string" + }, + "learning_style": { + "rating": "self-directed|guided|documentation-first|example-driven", + "confidence": "HIGH|MEDIUM|LOW|UNSCORED", + "evidence_count": 0, + "cross_project_consistent": true, + "evidence_quotes": [], + "summary": "string", + "claude_instruction": "string" + } + } +} +``` + +### Schema Notes + +- **`profile_version`**: Always `"1.0"` for this schema version +- **`analyzed_at`**: ISO-8601 timestamp of when the analysis was performed +- **`data_source`**: `"session_analysis"` for session-based profiling, `"questionnaire"` for questionnaire-only, `"hybrid"` for combined +- **`projects_analyzed`**: List of project names that contributed messages +- **`messages_analyzed`**: Total number of genuine user messages processed +- **`message_threshold`**: Which threshold mode was triggered (`full`, `hybrid`, `insufficient`) +- **`sensitive_excluded`**: Array of excluded sensitive content types with counts (empty array if none found) +- **`claude_instruction`**: Must be written in imperative form directed at OpenCode. This field is how the profile becomes actionable. + - Good: "Provide structured responses with headers and numbered lists to match this developer's communication style." + - Bad: "You tend to like structured responses." + - Good: "Ask before making changes beyond the stated request -- this developer values bounded execution." + - Bad: "The developer gets frustrated when you do extra work." + +--- + +## Cross-Project Consistency + +### Assessment + +For each dimension, assess whether the observed pattern is consistent across the projects analyzed: + +- **`cross_project_consistent: true`** -- Same rating would apply regardless of which project is analyzed. Evidence from 2+ projects shows the same pattern. +- **`cross_project_consistent: false`** -- Pattern varies by project. Include a context-dependent note in the summary. + +### Reporting Splits + +When `cross_project_consistent` is false, the summary must describe the split: + +- "Context-dependent: terse-direct for CLI/backend projects (gsd-tools, api-server), detailed-structured for frontend projects (dashboard, landing-page)." +- "Context-dependent: fast-intuitive for familiar tech (React, Node), research-first for new domains (Rust, ML)." + +The rating field should reflect the **dominant** pattern (most evidence). The summary describes the nuance. + +### Phase 3 Resolution + +Context-dependent splits are resolved during Phase 3 orchestration. The orchestrator presents the split to the developer and asks which pattern represents their general preference. Until resolved, OpenCode uses the dominant pattern with awareness of the context-dependent variation. + +--- + +*Reference document version: 1.0* +*Dimensions: 8* +*Schema: profile_version 1.0* diff --git a/gsd-opencode/get-shit-done/references/workstream-flag.md b/gsd-opencode/get-shit-done/references/workstream-flag.md new file mode 100644 index 0000000..9f2a519 --- /dev/null +++ b/gsd-opencode/get-shit-done/references/workstream-flag.md @@ -0,0 +1,58 @@ +# Workstream Flag (`--ws`) + +## Overview + +The `--ws ` flag scopes GSD operations to a specific workstream, enabling +parallel milestone work by multiple OpenCode instances on the same codebase. + +## Resolution Priority + +1. `--ws ` flag (explicit, highest priority) +2. `GSD_WORKSTREAM` environment variable (per-instance) +3. `.planning/active-workstream` file (shared, last-writer-wins) +4. `null` — flat mode (no workstreams) + +## Routing Propagation + +All workflow routing commands include `${GSD_WS}` which: +- Expands to `--ws ` when a workstream is active +- Expands to empty string in flat mode (backward compatible) + +This ensures workstream scope chains automatically through the workflow: +`new-milestone → discuss-phase → plan-phase → execute-phase → transition` + +## Directory Structure + +``` +.planning/ +├── PROJECT.md # Shared +├── config.json # Shared +├── milestones/ # Shared +├── codebase/ # Shared +├── active-workstream # Points to current ws +└── workstreams/ + ├── feature-a/ # Workstream A + │ ├── STATE.md + │ ├── ROADMAP.md + │ ├── REQUIREMENTS.md + │ └── phases/ + └── feature-b/ # Workstream B + ├── STATE.md + ├── ROADMAP.md + ├── REQUIREMENTS.md + └── phases/ +``` + +## CLI Usage + +```bash +# All gsd-tools commands accept --ws +node gsd-tools.cjs state json --ws feature-a +node gsd-tools.cjs find-phase 3 --ws feature-b + +# Workstream CRUD +node gsd-tools.cjs workstream create +node gsd-tools.cjs workstream list +node gsd-tools.cjs workstream status +node gsd-tools.cjs workstream complete +``` diff --git a/gsd-opencode/get-shit-done/templates/UAT.md b/gsd-opencode/get-shit-done/templates/UAT.md index 1a6f14b..5513767 100644 --- a/gsd-opencode/get-shit-done/templates/UAT.md +++ b/gsd-opencode/get-shit-done/templates/UAT.md @@ -8,7 +8,7 @@ Template for `.planning/phases/XX-name/{phase_num}-UAT.md` — persistent UAT se ```markdown --- -status: testing | complete | diagnosed +status: testing | partial | complete | diagnosed phase: XX-name source: [list of SUMMARY.md files tested] started: [ISO timestamp] @@ -45,6 +45,12 @@ expected: [observable behavior] result: skipped reason: [why skipped] +### 5. [Test Name] +expected: [observable behavior] +result: blocked +blocked_by: server | physical-device | release-build | third-party | prior-phase +reason: [why blocked] + ... ## Summary @@ -54,6 +60,7 @@ passed: [N] issues: [N] pending: [N] skipped: [N] +blocked: [N] ## Gaps @@ -74,7 +81,7 @@ skipped: [N] **Frontmatter:** -- `status`: OVERWRITE - "testing" or "complete" +- `status`: OVERWRITE - "testing", "partial", or "complete" - `phase`: IMMUTABLE - set on creation - `source`: IMMUTABLE - SUMMARY files being tested - `started`: IMMUTABLE - set on creation @@ -87,9 +94,10 @@ skipped: [N] **Tests:** - Each test: OVERWRITE result field when user responds -- `result` values: [pending], pass, issue, skipped +- `result` values: [pending], pass, issue, skipped, blocked - If issue: add `reported` (verbatim) and `severity` (inferred) - If skipped: add `reason` if provided +- If blocked: add `blocked_by` (tag) and `reason` (if provided) **Summary:** - OVERWRITE counts after each response @@ -156,6 +164,16 @@ skipped: [N] - Commit file - Present summary with next steps +**Partial completion:** +- status → "partial" (if pending, blocked, or unresolved skipped tests remain) +- Current Test → "[testing paused — {N} items outstanding]" +- Commit file +- Present summary with outstanding items highlighted + +**Resuming partial session:** +- `/gsd-verify-work {phase}` picks up from first pending/blocked test +- When all items resolved, status advances to "complete" + **Resume after /new:** 1. read frontmatter → know phase and status 2. read Current Test → know where we are diff --git a/gsd-opencode/get-shit-done/templates/UI-SPEC.md b/gsd-opencode/get-shit-done/templates/UI-SPEC.md new file mode 100644 index 0000000..be2c6e1 --- /dev/null +++ b/gsd-opencode/get-shit-done/templates/UI-SPEC.md @@ -0,0 +1,100 @@ +--- +phase: {N} +slug: {phase-slug} +status: draft +shadcn_initialized: false +preset: none +created: {date} +--- + +# Phase {N} — UI Design Contract + +> Visual and interaction contract for frontend phases. Generated by gsd-ui-researcher, verified by gsd-ui-checker. + +--- + +## Design System + +| Property | Value | +|----------|-------| +| Tool | {shadcn / none} | +| Preset | {preset string or "not applicable"} | +| Component library | {radix / base-ui / none} | +| Icon library | {library} | +| Font | {font} | + +--- + +## Spacing Scale + +Declared values (must be multiples of 4): + +| Token | Value | Usage | +|-------|-------|-------| +| xs | 4px | Icon gaps, inline padding | +| sm | 8px | Compact element spacing | +| md | 16px | Default element spacing | +| lg | 24px | Section padding | +| xl | 32px | Layout gaps | +| 2xl | 48px | Major section breaks | +| 3xl | 64px | Page-level spacing | + +Exceptions: {list any, or "none"} + +--- + +## Typography + +| Role | Size | Weight | Line Height | +|------|------|--------|-------------| +| Body | {px} | {weight} | {ratio} | +| Label | {px} | {weight} | {ratio} | +| Heading | {px} | {weight} | {ratio} | +| Display | {px} | {weight} | {ratio} | + +--- + +## Color + +| Role | Value | Usage | +|------|-------|-------| +| Dominant (60%) | {hex} | Background, surfaces | +| Secondary (30%) | {hex} | Cards, sidebar, nav | +| Accent (10%) | {hex} | {list specific elements only} | +| Destructive | {hex} | Destructive actions only | + +Accent reserved for: {explicit list — never "all interactive elements"} + +--- + +## Copywriting Contract + +| Element | Copy | +|---------|------| +| Primary CTA | {specific verb + noun} | +| Empty state heading | {copy} | +| Empty state body | {copy + next step} | +| Error state | {problem + solution path} | +| Destructive confirmation | {action name}: {confirmation copy} | + +--- + +## Registry Safety + +| Registry | Blocks Used | Safety Gate | +|----------|-------------|-------------| +| shadcn official | {list} | not required | +| {third-party name} | {list} | shadcn view + diff required | + +--- + +## Checker Sign-Off + +- [ ] Dimension 1 Copywriting: PASS +- [ ] Dimension 2 Visuals: PASS +- [ ] Dimension 3 Color: PASS +- [ ] Dimension 4 Typography: PASS +- [ ] Dimension 5 Spacing: PASS +- [ ] Dimension 6 Registry Safety: PASS + +**Approval:** {pending / approved YYYY-MM-DD} diff --git a/gsd-opencode/get-shit-done/templates/claude-md.md b/gsd-opencode/get-shit-done/templates/claude-md.md new file mode 100644 index 0000000..69fbfbf --- /dev/null +++ b/gsd-opencode/get-shit-done/templates/claude-md.md @@ -0,0 +1,122 @@ +# AGENTS.md Template + +Template for project-root `AGENTS.md` — auto-generated by `gsd-tools generate-OpenCode-md`. + +Contains 6 marker-bounded sections. Each section is independently updatable. +The `generate-OpenCode-md` subcommand manages 5 sections (project, stack, conventions, architecture, workflow enforcement). +The profile section is managed exclusively by `generate-OpenCode-profile`. + +--- + +## Section Templates + +### Project Section +``` + +## Project + +{{project_content}} + +``` + +**Fallback text:** +``` +Project not yet initialized. Run /gsd-new-project to set up. +``` + +### Stack Section +``` + +## Technology Stack + +{{stack_content}} + +``` + +**Fallback text:** +``` +Technology stack not yet documented. Will populate after codebase mapping or first phase. +``` + +### Conventions Section +``` + +## Conventions + +{{conventions_content}} + +``` + +**Fallback text:** +``` +Conventions not yet established. Will populate as patterns emerge during development. +``` + +### Architecture Section +``` + +## Architecture + +{{architecture_content}} + +``` + +**Fallback text:** +``` +Architecture not yet mapped. Follow existing patterns found in the codebase. +``` + +### Workflow Enforcement Section +``` + +## GSD Workflow Enforcement + +Before using edit, write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync. + +Use these entry points: +- `/gsd-quick` for small fixes, doc updates, and ad-hoc tasks +- `/gsd-debug` for investigation and bug fixing +- `/gsd-execute-phase` for planned phase work + +Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it. + +``` + +### Profile Section (Placeholder Only) +``` + +## Developer Profile + +> Profile not yet configured. Run `/gsd-profile-user` to generate your developer profile. +> This section is managed by `generate-OpenCode-profile` — do not edit manually. + +``` + +**Note:** This section is NOT managed by `generate-OpenCode-md`. It is managed exclusively +by `generate-OpenCode-profile`. The placeholder above is only used when creating a new +AGENTS.md file and no profile section exists yet. + +--- + +## Section Ordering + +1. **Project** — Identity and purpose (what this project is) +2. **Stack** — Technology choices (what tools are used) +3. **Conventions** — Code patterns and rules (how code is written) +4. **Architecture** — System structure (how components fit together) +5. **Workflow Enforcement** — Default GSD entry points for file-changing work +6. **Profile** — Developer behavioral preferences (how to interact) + +## Marker Format + +- Start: `` +- End: `` +- Source attribute enables targeted updates when source files change +- Partial match on start marker (without closing `-->`) for detection + +## Fallback Behavior + +When a source file is missing, fallback text provides OpenCode-actionable guidance: +- Guides OpenCode's behavior in the absence of data +- Not placeholder ads or "missing" notices +- Each fallback tells OpenCode what to do, not just what's absent diff --git a/gsd-opencode/get-shit-done/templates/config.json b/gsd-opencode/get-shit-done/templates/config.json index dde3cf7..fd147b6 100644 --- a/gsd-opencode/get-shit-done/templates/config.json +++ b/gsd-opencode/get-shit-done/templates/config.json @@ -6,11 +6,14 @@ "plan_check": true, "verifier": true, "auto_advance": false, - "nyquist_validation": true + "nyquist_validation": true, + "discuss_mode": "discuss", + "research_before_questions": false }, "planning": { "commit_docs": true, - "search_gitignored": false + "search_gitignored": false, + "sub_repos": [] }, "parallelization": { "enabled": true, @@ -33,5 +36,9 @@ "safety": { "always_confirm_destructive": true, "always_confirm_external_services": true - } + }, + "hooks": { + "context_warnings": true + }, + "agent_skills": {} } diff --git a/gsd-opencode/get-shit-done/templates/context.md b/gsd-opencode/get-shit-done/templates/context.md index 1883a47..06b56a3 100644 --- a/gsd-opencode/get-shit-done/templates/context.md +++ b/gsd-opencode/get-shit-done/templates/context.md @@ -31,14 +31,14 @@ Template for `.planning/phases/XX-name/{phase_num}-CONTEXT.md` - captures implem ## Implementation Decisions ### [Area 1 that was discussed] -- [Specific decision made] -- [Another decision if applicable] +- **D-01:** [Specific decision made] +- **D-02:** [Another decision if applicable] ### [Area 2 that was discussed] -- [Specific decision made] +- **D-03:** [Specific decision made] ### [Area 3 that was discussed] -- [Specific decision made] +- **D-04:** [Specific decision made] ### OpenCode's Discretion [Areas where user explicitly said "you decide" — OpenCode has flexibility here during planning/implementation] @@ -54,6 +54,24 @@ Template for `.planning/phases/XX-name/{phase_num}-CONTEXT.md` - captures implem + +## Canonical References + +**Downstream agents MUST read these before planning or implementing.** + +[List every spec, ADR, feature doc, or design doc that defines requirements or constraints for this phase. Use full relative paths so agents can read them directly. Group by topic area when the phase has multiple concerns.] + +### [Topic area 1] +- `path/to/spec-or-adr.md` — [What this doc decides/defines that's relevant] +- `path/to/doc.md` §N — [Specific section and what it covers] + +### [Topic area 2] +- `path/to/feature-doc.md` — [What capability this defines] + +[If the project has no external specs: "No external specs — requirements are fully captured in decisions above"] + + + ## Existing Code Insights @@ -124,6 +142,18 @@ Display posts from followed users in a scrollable feed. Users can view posts and + +## Canonical References + +### Feed display +- `docs/features/social-feed.md` — Feed requirements, post card fields, engagement display rules +- `docs/decisions/adr-012-infinite-scroll.md` — Scroll strategy decision, virtualization requirements + +### Empty states +- `docs/design/empty-states.md` — Empty state patterns, illustration guidelines + + + ## Specific Ideas @@ -186,6 +216,15 @@ CLI command to backup database to local file or S3. Supports full and incrementa + +## Canonical References + +### Backup CLI +- `docs/features/backup-restore.md` — Backup requirements, supported backends, encryption spec +- `docs/decisions/adr-007-cli-conventions.md` — Flag naming, exit codes, output format standards + + + ## Specific Ideas @@ -248,6 +287,15 @@ Organize existing photo library into structured folders. Handle duplicates and a + +## Canonical References + +### Organization rules +- `docs/features/photo-organization.md` — Grouping rules, duplicate policy, naming spec +- `docs/decisions/adr-003-exif-handling.md` — EXIF extraction strategy, fallback for missing metadata + + + ## Specific Ideas @@ -291,7 +339,14 @@ The output should answer: "What does the researcher need to investigate? What ch **After creation:** - File lives in phase directory: `.planning/phases/XX-name/{phase_num}-CONTEXT.md` -- `gsd-phase-researcher` uses decisions to focus investigation -- `gsd-planner` uses decisions + research to create executable tasks +- `gsd-phase-researcher` uses decisions to focus investigation AND reads canonical_refs to know WHAT docs to study +- `gsd-planner` uses decisions + research to create executable tasks AND reads canonical_refs to verify alignment - Downstream agents should NOT need to ask the user again about captured decisions + +**CRITICAL — Canonical references:** +- The `` section is MANDATORY. Every CONTEXT.md must have one. +- If your project has external specs, ADRs, or design docs, list them with full relative paths grouped by topic +- If ROADMAP.md lists `Canonical refs:` per phase, extract and expand those +- Inline mentions like "see ADR-019" scattered in decisions are useless to downstream agents — they need full paths and section references in a dedicated section they can find +- If no external specs exist, say so explicitly — don't silently omit the section diff --git a/gsd-opencode/get-shit-done/templates/dev-preferences.md b/gsd-opencode/get-shit-done/templates/dev-preferences.md new file mode 100644 index 0000000..2a0013c --- /dev/null +++ b/gsd-opencode/get-shit-done/templates/dev-preferences.md @@ -0,0 +1,21 @@ +--- +description: Load developer preferences into this session +--- + +# Developer Preferences + +> Generated by GSD on {{generated_at}} from {{data_source}}. +> Run `/gsd-profile-user --refresh` to regenerate. + +## Behavioral Directives + +Follow these directives when working with this developer. Higher confidence +directives should be applied directly. Lower confidence directives should be +tried with hedging ("Based on your profile, I'll try X -- let me know if +that's off"). + +{{behavioral_directives}} + +## Stack Preferences + +{{stack_preferences}} diff --git a/gsd-opencode/get-shit-done/templates/discussion-log.md b/gsd-opencode/get-shit-done/templates/discussion-log.md new file mode 100644 index 0000000..c96d8a5 --- /dev/null +++ b/gsd-opencode/get-shit-done/templates/discussion-log.md @@ -0,0 +1,63 @@ +# Discussion Log Template + +Template for `.planning/phases/XX-name/{phase_num}-DISCUSSION-LOG.md` — audit trail of discuss-phase Q&A sessions. + +**Purpose:** Software audit trail for decision-making. Captures all options considered, not just the selected one. Separate from CONTEXT.md which is the implementation artifact consumed by downstream agents. + +**NOT for LLM consumption.** This file should never be referenced in `` blocks or agent prompts. + +## Format + +```markdown +# Phase [X]: [Name] - Discussion Log + +> **Audit trail only.** Do not use as input to planning, research, or execution agents. +> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered. + +**Date:** [ISO date] +**Phase:** [phase number]-[phase name] +**Areas discussed:** [comma-separated list] + +--- + +## [Area 1 Name] + +| Option | Description | Selected | +|--------|-------------|----------| +| [Option 1] | [Brief description] | | +| [Option 2] | [Brief description] | ✓ | +| [Option 3] | [Brief description] | | + +**User's choice:** [Selected option or verbatim free-text response] +**Notes:** [Any clarifications or rationale provided during discussion] + +--- + +## [Area 2 Name] + +... + +--- + +## OpenCode's Discretion + +[Areas delegated to OpenCode's judgment — list what was deferred and why] + +## Deferred Ideas + +[Ideas mentioned but not in scope for this phase] + +--- + +*Phase: XX-name* +*Discussion log generated: [date]* +``` + +## Rules + +- Generated automatically at end of every discuss-phase session +- Includes ALL options considered, not just the selected one +- Includes user's freeform notes and clarifications +- Clearly marked as audit-only, not an implementation artifact +- Does NOT interfere with CONTEXT.md generation or downstream agent behavior +- Committed alongside CONTEXT.md in the same git commit diff --git a/gsd-opencode/get-shit-done/templates/phase-prompt.md b/gsd-opencode/get-shit-done/templates/phase-prompt.md index 5030f35..40bee11 100644 --- a/gsd-opencode/get-shit-done/templates/phase-prompt.md +++ b/gsd-opencode/get-shit-done/templates/phase-prompt.md @@ -63,21 +63,29 @@ Output: [What artifacts will be created] task 1: [Action-oriented name] path/to/file.ext, another/file.ext - [Specific implementation - what to do, how to do it, what to avoid and WHY] + path/to/reference.ext, path/to/source-of-truth.ext + [Specific implementation - what to do, how to do it, what to avoid and WHY. Include CONCRETE values: exact identifiers, parameters, expected outputs, file paths, command arguments. Never say "align X with Y" without specifying the exact target state.] [Command or check to prove it worked] + + - [grep-verifiable condition: "file.ext contains 'exact string'"] + - [Measurable condition: "output.ext uses 'expected-value', NOT 'wrong-value'"] + [Measurable acceptance criteria] task 2: [Action-oriented name] path/to/file.ext - [Specific implementation] + path/to/reference.ext + [Specific implementation with concrete values] [Command or check] + + - [grep-verifiable condition] + [Acceptance criteria] - [What needs deciding] @@ -333,7 +341,7 @@ Output: User model, API endpoints, and UI components. task 2: Create User API endpoints src/features/user/api.ts GET /users (list), GET /users/:id (single), POST /users (create). Use User type from model. - curl tests pass for all endpoints + fetch tests pass for all endpoints All CRUD operations work @@ -399,7 +407,7 @@ Output: Working dashboard component. Start dev server Run `npm run dev` in background, wait for ready - curl localhost:3000 returns 200 + fetch http://localhost:3000 returns 200 @@ -456,6 +464,39 @@ files_modified: [...] ``` +**Bad: Missing read_first (executor modifies files it hasn't read)** +```xml + + Update database config + src/config/database.ts + + Update the database config to match production settings + +``` + +**Bad: Vague acceptance criteria (not verifiable)** +```xml + + - Config is properly set up + - Database connection works correctly + +``` + +**Good: Concrete with read_first + verifiable criteria** +```xml + + Update database config for connection pooling + src/config/database.ts + src/config/database.ts, .env.example, docker-compose.yml + Add pool configuration: min=2, max=20, idleTimeoutMs=30000. Add SSL config: rejectUnauthorized=true when NODE_ENV=production. Add .env.example entry: DATABASE_POOL_MAX=20. + + - database.ts contains "max: 20" and "idleTimeoutMillis: 30000" + - database.ts contains SSL conditional on NODE_ENV + - .env.example contains DATABASE_POOL_MAX + + +``` + --- ## Guidelines diff --git a/gsd-opencode/get-shit-done/templates/project.md b/gsd-opencode/get-shit-done/templates/project.md index ad1e2dd..65a9f33 100644 --- a/gsd-opencode/get-shit-done/templates/project.md +++ b/gsd-opencode/get-shit-done/templates/project.md @@ -127,6 +127,8 @@ Common types: Tech stack, Timeline, Budget, Dependencies, Compatibility, Perform PROJECT.md evolves throughout the project lifecycle. +These rules are embedded in the generated PROJECT.md (## Evolution section) +and implemented by workflows/transition.md and workflows/complete-milestone.md. **After each phase transition:** 1. Requirements invalidated? → Move to Out of Scope with reason diff --git a/gsd-opencode/get-shit-done/templates/state.md b/gsd-opencode/get-shit-done/templates/state.md index 87e07b8..3633881 100644 --- a/gsd-opencode/get-shit-done/templates/state.md +++ b/gsd-opencode/get-shit-done/templates/state.md @@ -73,7 +73,7 @@ Stopped at: [Description of last completed action] Resume file: [Path to .continue-here*.md if exists, otherwise "None"] ``` - + STATE.md is the project's short-term memory spanning all phases and sessions. @@ -85,7 +85,7 @@ STATE.md is the project's short-term memory spanning all phases and sessions. - Contains digest of accumulated context - Enables instant session restoration - + diff --git a/gsd-opencode/get-shit-done/templates/user-profile.md b/gsd-opencode/get-shit-done/templates/user-profile.md new file mode 100644 index 0000000..0db17ca --- /dev/null +++ b/gsd-opencode/get-shit-done/templates/user-profile.md @@ -0,0 +1,146 @@ +# Developer Profile + +> This profile was generated from session analysis. It contains behavioral directives +> for OpenCode to follow when working with this developer. HIGH confidence dimensions +> should be acted on directly. LOW confidence dimensions should be approached with +> hedging ("Based on your profile, I'll try X -- let me know if that's off"). + +**Generated:** {{generated_at}} +**Source:** {{data_source}} +**Projects Analyzed:** {{projects_list}} +**Messages Analyzed:** {{message_count}} + +--- + +## Quick Reference + +{{summary_instructions}} + +--- + +## Communication Style + +**Rating:** {{communication_style.rating}} | **Confidence:** {{communication_style.confidence}} + +**Directive:** {{communication_style.claude_instruction}} + +{{communication_style.summary}} + +**Evidence:** + +{{communication_style.evidence}} + +--- + +## Decision Speed + +**Rating:** {{decision_speed.rating}} | **Confidence:** {{decision_speed.confidence}} + +**Directive:** {{decision_speed.claude_instruction}} + +{{decision_speed.summary}} + +**Evidence:** + +{{decision_speed.evidence}} + +--- + +## Explanation Depth + +**Rating:** {{explanation_depth.rating}} | **Confidence:** {{explanation_depth.confidence}} + +**Directive:** {{explanation_depth.claude_instruction}} + +{{explanation_depth.summary}} + +**Evidence:** + +{{explanation_depth.evidence}} + +--- + +## Debugging Approach + +**Rating:** {{debugging_approach.rating}} | **Confidence:** {{debugging_approach.confidence}} + +**Directive:** {{debugging_approach.claude_instruction}} + +{{debugging_approach.summary}} + +**Evidence:** + +{{debugging_approach.evidence}} + +--- + +## UX Philosophy + +**Rating:** {{ux_philosophy.rating}} | **Confidence:** {{ux_philosophy.confidence}} + +**Directive:** {{ux_philosophy.claude_instruction}} + +{{ux_philosophy.summary}} + +**Evidence:** + +{{ux_philosophy.evidence}} + +--- + +## Vendor Philosophy + +**Rating:** {{vendor_philosophy.rating}} | **Confidence:** {{vendor_philosophy.confidence}} + +**Directive:** {{vendor_philosophy.claude_instruction}} + +{{vendor_philosophy.summary}} + +**Evidence:** + +{{vendor_philosophy.evidence}} + +--- + +## Frustration Triggers + +**Rating:** {{frustration_triggers.rating}} | **Confidence:** {{frustration_triggers.confidence}} + +**Directive:** {{frustration_triggers.claude_instruction}} + +{{frustration_triggers.summary}} + +**Evidence:** + +{{frustration_triggers.evidence}} + +--- + +## Learning Style + +**Rating:** {{learning_style.rating}} | **Confidence:** {{learning_style.confidence}} + +**Directive:** {{learning_style.claude_instruction}} + +{{learning_style.summary}} + +**Evidence:** + +{{learning_style.evidence}} + +--- + +## Profile Metadata + +| Field | Value | +|-------|-------| +| Profile Version | {{profile_version}} | +| Generated | {{generated_at}} | +| Source | {{data_source}} | +| Projects | {{projects_count}} | +| Messages | {{message_count}} | +| Dimensions Scored | {{dimensions_scored}}/8 | +| High Confidence | {{high_confidence_count}} | +| Medium Confidence | {{medium_confidence_count}} | +| Low Confidence | {{low_confidence_count}} | +| Sensitive Content Excluded | {{sensitive_excluded_summary}} | diff --git a/gsd-opencode/get-shit-done/workflows/add-phase.md b/gsd-opencode/get-shit-done/workflows/add-phase.md index 85b5d72..6e64042 100644 --- a/gsd-opencode/get-shit-done/workflows/add-phase.md +++ b/gsd-opencode/get-shit-done/workflows/add-phase.md @@ -1,6 +1,6 @@ - + Add a new integer phase to the end of the current milestone in the roadmap. Automatically calculates next phase number, creates phase directory, and updates roadmap structure. - + read all files referenced by the invoking prompt's execution_context before starting. diff --git a/gsd-opencode/get-shit-done/workflows/add-tests.md b/gsd-opencode/get-shit-done/workflows/add-tests.md index de49cd0..64ed238 100644 --- a/gsd-opencode/get-shit-done/workflows/add-tests.md +++ b/gsd-opencode/get-shit-done/workflows/add-tests.md @@ -1,8 +1,8 @@ - + Generate unit and E2E tests for a completed phase based on its SUMMARY.md, CONTEXT.md, and implementation. Classifies each changed file into TDD (unit), E2E (browser), or Skip categories, presents a test plan for user approval, then generates tests following RED-GREEN conventions. Users currently hand-craft `/gsd-quick` prompts for test generation after each phase. This workflow standardizes the process with proper classification, quality gates, and gap reporting. - + read all files referenced by the invoking prompt's execution_context before starting. @@ -146,7 +146,7 @@ find . -type d -name "*test*" -o -name "*spec*" -o -name "*__tests__*" 2>/dev/nu # Find existing test files for convention matching find . -type f \( -name "*.test.*" -o -name "*.spec.*" -o -name "*Tests.fs" -o -name "*Test.fs" \) 2>/dev/null | head -20 # Check for test runners -ls package.json *.sln 2>/dev/null +ls package.json *.sln 2>/dev/null || true ``` Identify: @@ -243,7 +243,7 @@ For each approved E2E test: 1. **Check for existing tests** covering the same scenario: ```bash - grep -r "{scenario keyword}" {e2e test directory} 2>/dev/null + grep -r "{scenario keyword}" {e2e test directory} 2>/dev/null || true ``` If found, extend rather than duplicate. diff --git a/gsd-opencode/get-shit-done/workflows/add-todo.md b/gsd-opencode/get-shit-done/workflows/add-todo.md index 2e1fea1..8eda24c 100644 --- a/gsd-opencode/get-shit-done/workflows/add-todo.md +++ b/gsd-opencode/get-shit-done/workflows/add-todo.md @@ -1,6 +1,6 @@ - + Capture an idea, task, or issue that surfaces during a GSD session as a structured todo for later work. Enables "thought → capture → continue" flow without losing context. - + read all files referenced by the invoking prompt's execution_context before starting. @@ -63,7 +63,7 @@ Use existing area from step 2 if similar match exists. ```bash # Search for key words from title in existing todos -grep -l -i "[key words from title]" .planning/todos/pending/*.md 2>/dev/null +grep -l -i "[key words from title]" .planning/todos/pending/*.md 2>/dev/null || true ``` If potential duplicate found: diff --git a/gsd-opencode/get-shit-done/workflows/audit-milestone.md b/gsd-opencode/get-shit-done/workflows/audit-milestone.md index f96ccd6..4dccd51 100644 --- a/gsd-opencode/get-shit-done/workflows/audit-milestone.md +++ b/gsd-opencode/get-shit-done/workflows/audit-milestone.md @@ -1,11 +1,16 @@ - + Verify milestone achieved its definition of done by aggregating phase verifications, checking cross-phase integration, and assessing requirements coverage. Reads existing VERIFICATION.md files (phases already verified during execute-phase), aggregates tech debt and deferred gaps, then spawns integration checker for cross-phase wiring. - + read all files referenced by the invoking prompt's execution_context before starting. + +Valid GSD subagent types (use exact names — do not fall back to 'general'): +- gsd-integration-checker — Checks cross-phase integration + + ## 0. Initialize Milestone Context @@ -13,6 +18,7 @@ read all files referenced by the invoking prompt's execution_context before star ```bash INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init milestone-op) if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +AGENT_SKILLS_CHECKER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-integration-checker 2>/dev/null) ``` Extract from init JSON: `milestone_version`, `milestone_name`, `phase_count`, `completed_phases`, `commit_docs`. @@ -73,7 +79,8 @@ Milestone Requirements: MUST map each integration finding to affected requirement IDs where applicable. -Verify cross-phase wiring and E2E user flows.", +Verify cross-phase wiring and E2E user flows. +${AGENT_SKILLS_CHECKER}", subagent_type="gsd-integration-checker", model="{integration_checker_model}" ) @@ -105,7 +112,8 @@ For each phase's VERIFICATION.md, extract the expanded requirements table: For each phase's SUMMARY.md, extract `requirements-completed` from YAML frontmatter: ```bash for summary in .planning/phases/*-*/*-SUMMARY.md; do - node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" summary-extract "$summary" --fields requirements_completed | jq -r '.requirements_completed' + [ -e "$summary" ] || continue + node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" summary-extract "$summary" --fields requirements_completed --pick requirements_completed done ``` @@ -133,7 +141,7 @@ For each REQ-ID, determine status using all three sources: Skip if `workflow.nyquist_validation` is explicitly `false` (absent = enabled). ```bash -NYQUIST_CONFIG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config get workflow.nyquist_validation --raw 2>/dev/null) +NYQUIST_CONFIG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.nyquist_validation --raw 2>/dev/null) ``` If `false`: skip entirely. diff --git a/gsd-opencode/get-shit-done/workflows/audit-uat.md b/gsd-opencode/get-shit-done/workflows/audit-uat.md new file mode 100644 index 0000000..48831b0 --- /dev/null +++ b/gsd-opencode/get-shit-done/workflows/audit-uat.md @@ -0,0 +1,109 @@ + +Cross-phase audit of all UAT and verification files. Finds every outstanding item (pending, skipped, blocked, human_needed), optionally verifies against the codebase to detect stale docs, and produces a prioritized human test plan. + + + + + +Run the CLI audit: + +```bash +AUDIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" audit-uat --raw) +``` + +Parse JSON for `results` array and `summary` object. + +If `summary.total_items` is 0: +``` +## All Clear + +No outstanding UAT or verification items found across all phases. +All tests are passing, resolved, or diagnosed with fix plans. +``` +Stop here. + + + +Group items by what's actionable NOW vs. what needs prerequisites: + +**Testable Now** (no external dependencies): +- `pending` — tests never run +- `human_uat` — human verification items +- `skipped_unresolved` — skipped without clear blocking reason + +**Needs Prerequisites:** +- `server_blocked` — needs external server running +- `device_needed` — needs physical device (not simulator) +- `build_needed` — needs release/preview build +- `third_party` — needs external service configuration + +For each item in "Testable Now", use grep/read to check if the underlying feature still exists in the codebase: +- If the test references a component/function that no longer exists → mark as `stale` +- If the test references code that has been significantly rewritten → mark as `needs_update` +- Otherwise → mark as `active` + + + +Present the audit report: + +``` +## UAT Audit Report + +**{total_items} outstanding items across {total_files} files in {phase_count} phases** + +### Testable Now ({count}) + +| # | Phase | Test | Description | Status | +|---|-------|------|-------------|--------| +| 1 | {phase} | {test_name} | {expected} | {active/stale/needs_update} | +... + +### Needs Prerequisites ({count}) + +| # | Phase | Test | Blocked By | Description | +|---|-------|------|------------|-------------| +| 1 | {phase} | {test_name} | {category} | {expected} | +... + +### Stale (can be closed) ({count}) + +| # | Phase | Test | Why Stale | +|---|-------|------|-----------| +| 1 | {phase} | {test_name} | {reason} | +... + +--- + +## Recommended Actions + +1. **Close stale items:** `/gsd-verify-work {phase}` — mark stale tests as resolved +2. **Run active tests:** Human UAT test plan below +3. **When prerequisites met:** Retest blocked items with `/gsd-verify-work {phase}` +``` + + + +Generate a human UAT test plan for "Testable Now" + "active" items only: + +Group by what can be tested together (same screen, same feature, same prerequisite): + +``` +## Human UAT Test Plan + +### Group 1: {category — e.g., "Billing Flow"} +Prerequisites: {what needs to be running/configured} + +1. **{Test name}** (Phase {N}) + - Navigate to: {where} + - Do: {action} + - Expected: {expected behavior} + +2. **{Test name}** (Phase {N}) + ... + +### Group 2: {category} +... +``` + + + diff --git a/gsd-opencode/get-shit-done/workflows/autonomous.md b/gsd-opencode/get-shit-done/workflows/autonomous.md new file mode 100644 index 0000000..38796a4 --- /dev/null +++ b/gsd-opencode/get-shit-done/workflows/autonomous.md @@ -0,0 +1,891 @@ + + +Drive all remaining milestone phases autonomously. For each incomplete phase: discuss → plan → execute using skill() flat invocations. Pauses only for explicit user decisions (grey area acceptance, blockers, validation requests). Re-reads ROADMAP.md after each phase to catch dynamically inserted phases. + + + + + +read all files referenced by the invoking prompt's execution_context before starting. + + + + + + + +## 1. Initialize + +Parse `$ARGUMENTS` for `--from N` flag: + +```bash +FROM_PHASE="" +if echo "$ARGUMENTS" | grep -qE '\-\-from\s+[0-9]'; then + FROM_PHASE=$(echo "$ARGUMENTS" | grep -oE '\-\-from\s+[0-9]+\.?[0-9]*' | awk '{print $2}') +fi +``` + +Bootstrap via milestone-level init: + +```bash +INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init milestone-op) +if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +``` + +Parse JSON for: `milestone_version`, `milestone_name`, `phase_count`, `completed_phases`, `roadmap_exists`, `state_exists`, `commit_docs`. + +**If `roadmap_exists` is false:** Error — "No ROADMAP.md found. Run `/gsd-new-milestone` first." +**If `state_exists` is false:** Error — "No STATE.md found. Run `/gsd-new-milestone` first." + +Display startup banner: + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► AUTONOMOUS +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + Milestone: {milestone_version} — {milestone_name} + Phases: {phase_count} total, {completed_phases} complete +``` + +If `FROM_PHASE` is set, display: `Starting from phase ${FROM_PHASE}` + + + + + +## 2. Discover Phases + +Run phase discovery: + +```bash +ROADMAP=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap analyze) +``` + +Parse the JSON `phases` array. + +**Filter to incomplete phases:** Keep only phases where `disk_status !== "complete"` OR `roadmap_complete === false`. + +**Apply `--from N` filter:** If `FROM_PHASE` was provided, additionally filter out phases where `number < FROM_PHASE` (use numeric comparison — handles decimal phases like "5.1"). + +**Sort by `number`** in numeric ascending order. + +**If no incomplete phases remain:** + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► AUTONOMOUS ▸ COMPLETE 🎉 +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + All phases complete! Nothing left to do. +``` + +Exit cleanly. + +**Display phase plan:** + +``` +## Phase Plan + +| # | Phase | Status | +|---|-------|--------| +| 5 | skill Scaffolding & Phase Discovery | In Progress | +| 6 | Smart Discuss | Not Started | +| 7 | Auto-Chain Refinements | Not Started | +| 8 | Lifecycle Orchestration | Not Started | +``` + +**Fetch details for each phase:** + +```bash +DETAIL=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase ${PHASE_NUM}) +``` + +Extract `phase_name`, `goal`, `success_criteria` from each. Store for use in execute_phase and transition messages. + + + + + +## 3. Execute Phase + +For the current phase, display the progress banner: + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► AUTONOMOUS ▸ Phase {N}/{T}: {Name} [████░░░░] {P}% +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +Where N = current phase number (from the ROADMAP, e.g., 6), T = total milestone phases (from `phase_count` parsed in initialize step, e.g., 8), P = percentage of all milestone phases completed so far. Calculate P as: (number of phases with `disk_status` "complete" from the latest `roadmap analyze` / T × 100). Use █ for filled and ░ for empty segments in the progress bar (8 characters wide). + +**3a. Smart Discuss** + +Check if CONTEXT.md already exists for this phase: + +```bash +PHASE_STATE=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init phase-op ${PHASE_NUM}) +``` + +Parse `has_context` from JSON. + +**If has_context is true:** Skip discuss — context already gathered. Display: + +``` +Phase ${PHASE_NUM}: Context exists — skipping discuss. +``` + +Proceed to 3b. + +**If has_context is false:** Check if discuss is disabled via settings: + +```bash +SKIP_DISCUSS=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.skip_discuss 2>/dev/null || echo "false") +``` + +**If SKIP_DISCUSS is `true`:** Skip discuss entirely — the ROADMAP phase description is the spec. Display: + +``` +Phase ${PHASE_NUM}: Discuss skipped (workflow.skip_discuss=true) — using ROADMAP phase goal as spec. +``` + +write a minimal CONTEXT.md so downstream plan-phase has valid input. Get phase details: + +```bash +DETAIL=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase ${PHASE_NUM}) +``` + +Extract `goal` and `requirements` from JSON. write `${phase_dir}/${padded_phase}-CONTEXT.md` with: + +```markdown +# Phase {PHASE_NUM}: {Phase Name} - Context + +**Gathered:** {date} +**Status:** Ready for planning +**Mode:** Auto-generated (discuss skipped via workflow.skip_discuss) + + +## Phase Boundary + +{goal from ROADMAP phase description} + + + + +## Implementation Decisions + +### OpenCode's Discretion +All implementation choices are at OpenCode's discretion — discuss phase was skipped per user setting. Use ROADMAP phase goal, success criteria, and codebase conventions to guide decisions. + + + + +## Existing Code Insights + +Codebase context will be gathered during plan-phase research. + + + + +## Specific Ideas + +No specific requirements — discuss phase skipped. Refer to ROADMAP phase description and success criteria. + + + + +## Deferred Ideas + +None — discuss phase skipped. + + +``` + +Commit the minimal context: + +```bash +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs(${PADDED_PHASE}): auto-generated context (discuss skipped)" --files "${phase_dir}/${padded_phase}-CONTEXT.md" +``` + +Proceed to 3b. + +**If SKIP_DISCUSS is `false` (or unset):** Execute the smart_discuss step for this phase. + +After smart_discuss completes, verify context was written: + +```bash +PHASE_STATE=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init phase-op ${PHASE_NUM}) +``` + +Check `has_context`. If false → go to handle_blocker: "Smart discuss for phase ${PHASE_NUM} did not produce CONTEXT.md." + +**3a.5. UI Design Contract (Frontend Phases)** + +Check if this phase has frontend indicators and whether a UI-SPEC already exists: + +```bash +PHASE_SECTION=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase ${PHASE_NUM} 2>/dev/null) +echo "$PHASE_SECTION" | grep -iE "UI|interface|frontend|component|layout|page|screen|view|form|dashboard|widget" > /dev/null 2>&1 +HAS_UI=$? +UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1) +``` + +Check if UI phase workflow is enabled: + +```bash +UI_PHASE_CFG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.ui_phase 2>/dev/null || echo "true") +``` + +**If `HAS_UI` is 0 (frontend indicators found) AND `UI_SPEC_FILE` is empty (no UI-SPEC exists) AND `UI_PHASE_CFG` is not `false`:** + +Display: + +``` +Phase ${PHASE_NUM}: Frontend phase detected — generating UI design contract... +``` + +``` +skill(skill="gsd-ui-phase", args="${PHASE_NUM}") +``` + +Verify UI-SPEC was created: + +```bash +UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1) +``` + +**If `UI_SPEC_FILE` is still empty after ui-phase:** Display warning `Phase ${PHASE_NUM}: UI-SPEC generation did not produce output — continuing without design contract.` and proceed to 3b. + +**If `HAS_UI` is 1 (no frontend indicators) OR `UI_SPEC_FILE` is not empty (UI-SPEC already exists) OR `UI_PHASE_CFG` is `false`:** Skip silently to 3b. + +**3b. Plan** + +``` +skill(skill="gsd-plan-phase", args="${PHASE_NUM}") +``` + +Verify plan produced output — re-run `init phase-op` and check `has_plans`. If false → go to handle_blocker: "Plan phase ${PHASE_NUM} did not produce any plans." + +**3c. Execute** + +``` +skill(skill="gsd-execute-phase", args="${PHASE_NUM} --no-transition") +``` + +**3d. Post-Execution Routing** + +After execute-phase returns, read the verification result: + +```bash +VERIFY_STATUS=$(grep "^status:" "${PHASE_DIR}"/*-VERIFICATION.md 2>/dev/null | head -1 | cut -d: -f2 | tr -d ' ') +``` + +Where `PHASE_DIR` comes from the `init phase-op` call already made in step 3a. If the variable is not in scope, re-fetch: + +```bash +PHASE_STATE=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init phase-op ${PHASE_NUM}) +``` + +Parse `phase_dir` from the JSON. + +**If VERIFY_STATUS is empty** (no VERIFICATION.md or no status field): + +Go to handle_blocker: "Execute phase ${PHASE_NUM} did not produce verification results." + +**If `passed`:** + +Display: +``` +Phase ${PHASE_NUM} ✅ ${PHASE_NAME} — Verification passed +``` + +Proceed to iterate step. + +**If `human_needed`:** + +read the human_verification section from VERIFICATION.md to get the count and items requiring manual testing. + +Display the items, then ask user via question: +- **question:** "Phase ${PHASE_NUM} has items needing manual verification. Validate now or continue to next phase?" +- **options:** "Validate now" / "Continue without validation" + +On **"Validate now"**: Present the specific items from VERIFICATION.md's human_verification section. After user reviews, ask: +- **question:** "Validation result?" +- **options:** "All good — continue" / "Found issues" + +On "All good — continue": Display `Phase ${PHASE_NUM} ✅ Human validation passed` and proceed to iterate step. + +On "Found issues": Go to handle_blocker with the user's reported issues as the description. + +On **"Continue without validation"**: Display `Phase ${PHASE_NUM} ⏭ Human validation deferred` and proceed to iterate step. + +**If `gaps_found`:** + +read gap summary from VERIFICATION.md (score and missing items). Display: +``` +⚠ Phase ${PHASE_NUM}: ${PHASE_NAME} — Gaps Found +Score: {N}/{M} must-haves verified +``` + +Ask user via question: +- **question:** "Gaps found in phase ${PHASE_NUM}. How to proceed?" +- **options:** "Run gap closure" / "Continue without fixing" / "Stop autonomous mode" + +On **"Run gap closure"**: Execute gap closure cycle (limit: 1 attempt): + +``` +skill(skill="gsd-plan-phase", args="${PHASE_NUM} --gaps") +``` + +Verify gap plans were created — re-run `init phase-op ${PHASE_NUM}` and check `has_plans`. If no new gap plans → go to handle_blocker: "Gap closure planning for phase ${PHASE_NUM} did not produce plans." + +Re-execute: +``` +skill(skill="gsd-execute-phase", args="${PHASE_NUM} --no-transition") +``` + +Re-read verification status: +```bash +VERIFY_STATUS=$(grep "^status:" "${PHASE_DIR}"/*-VERIFICATION.md 2>/dev/null | head -1 | cut -d: -f2 | tr -d ' ') +``` + +If `passed` or `human_needed`: Route normally (continue or ask user as above). + +If still `gaps_found` after this retry: Display "Gaps persist after closure attempt." and ask via question: +- **question:** "Gap closure did not fully resolve issues. How to proceed?" +- **options:** "Continue anyway" / "Stop autonomous mode" + +On "Continue anyway": Proceed to iterate step. +On "Stop autonomous mode": Go to handle_blocker. + +This limits gap closure to 1 automatic retry to prevent infinite loops. + +On **"Continue without fixing"**: Display `Phase ${PHASE_NUM} ⏭ Gaps deferred` and proceed to iterate step. + +On **"Stop autonomous mode"**: Go to handle_blocker with "User stopped — gaps remain in phase ${PHASE_NUM}". + +**3d.5. UI Review (Frontend Phases)** + +> Run after any successful execution routing (passed, human_needed accepted, or gaps deferred/accepted) — before proceeding to the iterate step. + +Check if this phase had a UI-SPEC (created in step 3a.5 or pre-existing): + +```bash +UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1) +``` + +Check if UI review is enabled: + +```bash +UI_REVIEW_CFG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.ui_review 2>/dev/null || echo "true") +``` + +**If `UI_SPEC_FILE` is not empty AND `UI_REVIEW_CFG` is not `false`:** + +Display: + +``` +Phase ${PHASE_NUM}: Frontend phase with UI-SPEC — running UI review audit... +``` + +``` +skill(skill="gsd-ui-review", args="${PHASE_NUM}") +``` + +Display the review result summary (score from UI-REVIEW.md if produced). Continue to iterate step regardless of score — UI review is advisory, not blocking. + +**If `UI_SPEC_FILE` is empty OR `UI_REVIEW_CFG` is `false`:** Skip silently to iterate step. + + + + + +## Smart Discuss + +Run smart discuss for the current phase. Proposes grey area answers in batch tables — the user accepts or overrides per area. Produces identical CONTEXT.md output to regular discuss-phase. + +> **Note:** Smart discuss is an autonomous-optimized variant of the `gsd-discuss-phase` skill. It produces identical CONTEXT.md output but uses batch table proposals instead of sequential questioning. The original `discuss-phase` skill remains unchanged (per CTRL-03). Future milestones may extract this to a separate skill file. + +**Inputs:** `PHASE_NUM` from execute_phase. Run init to get phase paths: + +```bash +PHASE_STATE=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init phase-op ${PHASE_NUM}) +``` + +Parse from JSON: `phase_dir`, `phase_slug`, `padded_phase`, `phase_name`. + +--- + +### Sub-step 1: Load prior context + +read project-level and prior phase context to avoid re-asking decided questions. + +**read project files:** + +```bash +cat .planning/PROJECT.md 2>/dev/null || true +cat .planning/REQUIREMENTS.md 2>/dev/null || true +cat .planning/STATE.md 2>/dev/null || true +``` + +Extract from these: +- **PROJECT.md** — Vision, principles, non-negotiables, user preferences +- **REQUIREMENTS.md** — Acceptance criteria, constraints, must-haves vs nice-to-haves +- **STATE.md** — Current progress, decisions logged so far + +**read all prior CONTEXT.md files:** + +```bash +(find .planning/phases -name "*-CONTEXT.md" 2>/dev/null || true) | sort +``` + +For each CONTEXT.md where phase number < current phase: +- read the `` section — these are locked preferences +- read `` — particular references or "I want it like X" moments +- Note patterns (e.g., "user consistently prefers minimal UI", "user rejected verbose output") + +**Build internal prior_decisions context** (do not write to file): + +``` + +## Project-Level +- [Key principle or constraint from PROJECT.md] +- [Requirement affecting this phase from REQUIREMENTS.md] + +## From Prior Phases +### Phase N: [Name] +- [Decision relevant to current phase] +- [Preference that establishes a pattern] + +``` + +If no prior context exists, continue without — expected for early phases. + +--- + +### Sub-step 2: Scout Codebase + +Lightweight codebase scan to inform grey area identification and proposals. Keep under ~5% context. + +**Check for existing codebase maps:** + +```bash +ls .planning/codebase/*.md 2>/dev/null || true +``` + +**If codebase maps exist:** read the most relevant ones (CONVENTIONS.md, STRUCTURE.md, STACK.md based on phase type). Extract reusable components, established patterns, integration points. Skip to building context below. + +**If no codebase maps, do targeted grep:** + +Extract key terms from the phase goal. Search for related files: + +```bash +grep -rl "{term1}\|{term2}" src/ app/ --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" 2>/dev/null | head -10 || true +ls src/components/ src/hooks/ src/lib/ src/utils/ 2>/dev/null || true +``` + +read the 3-5 most relevant files to understand existing patterns. + +**Build internal codebase_context** (do not write to file): +- **Reusable assets** — existing components, hooks, utilities usable in this phase +- **Established patterns** — how the codebase does state management, styling, data fetching +- **Integration points** — where new code connects (routes, nav, providers) + +--- + +### Sub-step 3: Analyze Phase and Generate Proposals + +**Get phase details:** + +```bash +DETAIL=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase ${PHASE_NUM}) +``` + +Extract `goal`, `requirements`, `success_criteria` from the JSON response. + +**Infrastructure detection — check FIRST before generating grey areas:** + +A phase is pure infrastructure when ALL of these are true: +1. Goal keywords match: "scaffolding", "plumbing", "setup", "configuration", "migration", "refactor", "rename", "restructure", "upgrade", "infrastructure" +2. AND success criteria are all technical: "file exists", "test passes", "config valid", "command runs" +3. AND no user-facing behavior is described (no "users can", "displays", "shows", "presents") + +**If infrastructure-only:** Skip Sub-step 4. Jump directly to Sub-step 5 with minimal CONTEXT.md. Display: + +``` +Phase ${PHASE_NUM}: Infrastructure phase — skipping discuss, writing minimal context. +``` + +Use these defaults for the CONTEXT.md: +- ``: Phase boundary from ROADMAP goal +- ``: Single "### OpenCode's Discretion" subsection — "All implementation choices are at OpenCode's discretion — pure infrastructure phase" +- ``: Whatever the codebase scout found +- ``: "No specific requirements — infrastructure phase" +- ``: "None" + +**If NOT infrastructure — generate grey area proposals:** + +Determine domain type from the phase goal: +- Something users **SEE** → visual: layout, interactions, states, density +- Something users **CALL** → interface: contracts, responses, errors, auth +- Something users **RUN** → execution: invocation, output, behavior modes, flags +- Something users **READ** → content: structure, tone, depth, flow +- Something being **ORGANIZED** → organization: criteria, grouping, exceptions, naming + +Check prior_decisions — skip grey areas already decided in prior phases. + +Generate **3-4 grey areas** with **~4 questions each**. For each question: +- **Pre-select a recommended answer** based on: prior decisions (consistency), codebase patterns (reuse), domain conventions (standard approaches), ROADMAP success criteria +- Generate **1-2 alternatives** per question +- **Annotate** with prior decision context ("You decided X in Phase N") and code context ("Component Y exists with Z variants") where relevant + +--- + +### Sub-step 4: Present Proposals Per Area + +Present grey areas **one at a time**. For each area (M of N): + +Display a table: + +``` +### Grey Area {M}/{N}: {Area Name} + +| # | question | ✅ Recommended | Alternative(s) | +|---|----------|---------------|-----------------| +| 1 | {question} | {answer} — {rationale} | {alt1}; {alt2} | +| 2 | {question} | {answer} — {rationale} | {alt1} | +| 3 | {question} | {answer} — {rationale} | {alt1}; {alt2} | +| 4 | {question} | {answer} — {rationale} | {alt1} | +``` + +Then prompt the user via **question**: +- **header:** "Area {M}/{N}" +- **question:** "Accept these answers for {Area Name}?" +- **options:** Build dynamically — always "Accept all" first, then "Change Q1" through "Change QN" for each question (up to 4), then "Discuss deeper" last. Cap at 6 explicit options max (question adds "Other" automatically). + +**On "Accept all":** Record all recommended answers for this area. Move to next area. + +**On "Change QN":** Use question with the alternatives for that specific question: +- **header:** "{Area Name}" +- **question:** "Q{N}: {question text}" +- **options:** List the 1-2 alternatives plus "You decide" (maps to OpenCode's Discretion) + +Record the user's choice. Re-display the updated table with the change reflected. Re-present the full acceptance prompt so the user can make additional changes or accept. + +**On "Discuss deeper":** Switch to interactive mode for this area only — ask questions one at a time using question with 2-3 concrete options per question plus "You decide". After 4 questions, prompt: +- **header:** "{Area Name}" +- **question:** "More questions about {area name}, or move to next?" +- **options:** "More questions" / "Next area" + +If "More questions", ask 4 more. If "Next area", display final summary table of captured answers for this area and move on. + +**On "Other" (free text):** Interpret as either a specific change request or general feedback. Incorporate into the area's decisions, re-display updated table, re-present acceptance prompt. + +**Scope creep handling:** If user mentions something outside the phase domain: + +``` +"{Feature} sounds like a new capability — that belongs in its own phase. +I'll note it as a deferred idea. + +Back to {current area}: {return to current question}" +``` + +Track deferred ideas internally for inclusion in CONTEXT.md. + +--- + +### Sub-step 5: write CONTEXT.md + +After all areas are resolved (or infrastructure skip), write the CONTEXT.md file. + +**File path:** `${phase_dir}/${padded_phase}-CONTEXT.md` + +Use **exactly** this structure (identical to discuss-phase output): + +```markdown +# Phase {PHASE_NUM}: {Phase Name} - Context + +**Gathered:** {date} +**Status:** Ready for planning + + +## Phase Boundary + +{Domain boundary statement from analysis — what this phase delivers} + + + + +## Implementation Decisions + +### {Area 1 Name} +- {Accepted/chosen answer for Q1} +- {Accepted/chosen answer for Q2} +- {Accepted/chosen answer for Q3} +- {Accepted/chosen answer for Q4} + +### {Area 2 Name} +- {Accepted/chosen answer for Q1} +- {Accepted/chosen answer for Q2} +... + +### OpenCode's Discretion +{Any "You decide" answers collected — note OpenCode has flexibility here} + + + + +## Existing Code Insights + +### Reusable Assets +- {From codebase scout — components, hooks, utilities} + +### Established Patterns +- {From codebase scout — state management, styling, data fetching} + +### Integration Points +- {From codebase scout — where new code connects} + + + + +## Specific Ideas + +{Any specific references or "I want it like X" from discussion} +{If none: "No specific requirements — open to standard approaches"} + + + + +## Deferred Ideas + +{Ideas captured but out of scope for this phase} +{If none: "None — discussion stayed within phase scope"} + + +``` + +write the file. + +**Commit:** + +```bash +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs(${PADDED_PHASE}): smart discuss context" --files "${phase_dir}/${padded_phase}-CONTEXT.md" +``` + +Display confirmation: + +``` +Created: {path} +Decisions captured: {count} across {area_count} areas +``` + + + + + +## 4. Iterate + +After each phase completes, re-read ROADMAP.md to catch phases inserted mid-execution (decimal phases like 5.1): + +```bash +ROADMAP=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap analyze) +``` + +Re-filter incomplete phases using the same logic as discover_phases: +- Keep phases where `disk_status !== "complete"` OR `roadmap_complete === false` +- Apply `--from N` filter if originally provided +- Sort by number ascending + +read STATE.md fresh: + +```bash +cat .planning/STATE.md +``` + +Check for blockers in the Blockers/Concerns section. If blockers are found, go to handle_blocker with the blocker description. + +If incomplete phases remain: proceed to next phase, loop back to execute_phase. + +If all phases complete, proceed to lifecycle step. + + + + + +## 5. Lifecycle + +After all phases complete, run the milestone lifecycle sequence: audit → complete → cleanup. + +Display lifecycle transition banner: + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► AUTONOMOUS ▸ LIFECYCLE +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + All phases complete → Starting lifecycle: audit → complete → cleanup + Milestone: {milestone_version} — {milestone_name} +``` + +**5a. Audit** + +``` +skill(skill="gsd-audit-milestone") +``` + +After audit completes, detect the result: + +```bash +AUDIT_FILE=".planning/v${milestone_version}-MILESTONE-AUDIT.md" +AUDIT_STATUS=$(grep "^status:" "${AUDIT_FILE}" 2>/dev/null | head -1 | cut -d: -f2 | tr -d ' ') +``` + +**If AUDIT_STATUS is empty** (no audit file or no status field): + +Go to handle_blocker: "Audit did not produce results — audit file missing or malformed." + +**If `passed`:** + +Display: +``` +Audit ✅ passed — proceeding to complete milestone +``` + +Proceed to 5b (no user pause — per CTRL-01). + +**If `gaps_found`:** + +read the gaps summary from the audit file. Display: +``` +⚠ Audit: Gaps Found +``` + +Ask user via question: +- **question:** "Milestone audit found gaps. How to proceed?" +- **options:** "Continue anyway — accept gaps" / "Stop — fix gaps manually" + +On **"Continue anyway"**: Display `Audit ⏭ Gaps accepted — proceeding to complete milestone` and proceed to 5b. + +On **"Stop"**: Go to handle_blocker with "User stopped — audit gaps remain. Run /gsd-audit-milestone to review, then /gsd-complete-milestone when ready." + +**If `tech_debt`:** + +read the tech debt summary from the audit file. Display: +``` +⚠ Audit: Tech Debt Identified +``` + +Show the summary, then ask user via question: +- **question:** "Milestone audit found tech debt. How to proceed?" +- **options:** "Continue with tech debt" / "Stop — address debt first" + +On **"Continue with tech debt"**: Display `Audit ⏭ Tech debt acknowledged — proceeding to complete milestone` and proceed to 5b. + +On **"Stop"**: Go to handle_blocker with "User stopped — tech debt to address. Run /gsd-audit-milestone to review details." + +**5b. Complete Milestone** + +``` +skill(skill="gsd-complete-milestone", args="${milestone_version}") +``` + +After complete-milestone returns, verify it produced output: + +```bash +ls .planning/milestones/v${milestone_version}-ROADMAP.md 2>/dev/null || true +``` + +If the archive file does not exist, go to handle_blocker: "Complete milestone did not produce expected archive files." + +**5c. Cleanup** + +``` +skill(skill="gsd-cleanup") +``` + +Cleanup shows its own dry-run and asks user for approval internally — this is an acceptable pause per CTRL-01 since it's an explicit decision about file deletion. + +**5d. Final Completion** + +Display final completion banner: + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► AUTONOMOUS ▸ COMPLETE 🎉 +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + Milestone: {milestone_version} — {milestone_name} + Status: Complete ✅ + Lifecycle: audit ✅ → complete ✅ → cleanup ✅ + + Ship it! 🚀 +``` + + + + + +## 6. Handle Blocker + +When any phase operation fails or a blocker is detected, present 3 options via question: + +**Prompt:** "Phase {N} ({Name}) encountered an issue: {description}" + +**Options:** +1. **"Fix and retry"** — Re-run the failed step (discuss, plan, or execute) for this phase +2. **"Skip this phase"** — Mark phase as skipped, continue to the next incomplete phase +3. **"Stop autonomous mode"** — Display summary of progress so far and exit cleanly + +**On "Fix and retry":** Loop back to the failed step within execute_phase. If the same step fails again after retry, re-present these options. + +**On "Skip this phase":** Log `Phase {N} ⏭ {Name} — Skipped by user` and proceed to iterate. + +**On "Stop autonomous mode":** Display progress summary: + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► AUTONOMOUS ▸ STOPPED +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + Completed: {list of completed phases} + Skipped: {list of skipped phases} + Remaining: {list of remaining phases} + + Resume with: /gsd-autonomous --from {next_phase} +``` + + + + + + +- [ ] All incomplete phases executed in order (smart discuss → ui-phase → plan → execute → ui-review each) +- [ ] Smart discuss proposes grey area answers in tables, user accepts or overrides per area +- [ ] Progress banners displayed between phases +- [ ] Execute-phase invoked with --no-transition (autonomous manages transitions) +- [ ] Post-execution verification reads VERIFICATION.md and routes on status +- [ ] Passed verification → automatic continue to next phase +- [ ] Human-needed verification → user prompted to validate or skip +- [ ] Gaps-found → user offered gap closure, continue, or stop +- [ ] Gap closure limited to 1 retry (prevents infinite loops) +- [ ] Plan-phase and execute-phase failures route to handle_blocker +- [ ] ROADMAP.md re-read after each phase (catches inserted phases) +- [ ] STATE.md checked for blockers before each phase +- [ ] Blockers handled via user choice (retry / skip / stop) +- [ ] Final completion or stop summary displayed +- [ ] After all phases complete, lifecycle step is invoked (not manual suggestion) +- [ ] Lifecycle transition banner displayed before audit +- [ ] Audit invoked via skill(skill="gsd-audit-milestone") +- [ ] Audit result routing: passed → auto-continue, gaps_found → user decides, tech_debt → user decides +- [ ] Audit technical failure (no file/no status) routes to handle_blocker +- [ ] Complete-milestone invoked via skill() with ${milestone_version} arg +- [ ] Cleanup invoked via skill() — internal confirmation is acceptable (CTRL-01) +- [ ] Final completion banner displayed after lifecycle +- [ ] Progress bar uses phase number / total milestone phases (not position among incomplete) +- [ ] Smart discuss documents relationship to discuss-phase with CTRL-03 note +- [ ] Frontend phases get UI-SPEC generated before planning (step 3a.5) if not already present +- [ ] Frontend phases get UI review audit after successful execution (step 3d.5) if UI-SPEC exists +- [ ] UI phase and UI review respect workflow.ui_phase and workflow.ui_review config toggles +- [ ] UI review is advisory (non-blocking) — phase proceeds to iterate regardless of score + diff --git a/gsd-opencode/get-shit-done/workflows/check-todos.md b/gsd-opencode/get-shit-done/workflows/check-todos.md index 88d66ad..8ac52eb 100644 --- a/gsd-opencode/get-shit-done/workflows/check-todos.md +++ b/gsd-opencode/get-shit-done/workflows/check-todos.md @@ -1,6 +1,6 @@ - + List all pending todos, allow selection, load full context for the selected todo, and route to appropriate action. - + read all files referenced by the invoking prompt's execution_context before starting. diff --git a/gsd-opencode/get-shit-done/workflows/cleanup.md b/gsd-opencode/get-shit-done/workflows/cleanup.md index ce64160..2fdd5dc 100644 --- a/gsd-opencode/get-shit-done/workflows/cleanup.md +++ b/gsd-opencode/get-shit-done/workflows/cleanup.md @@ -1,8 +1,8 @@ - + Archive accumulated phase directories from completed milestones into `.planning/milestones/v{X.Y}-phases/`. Identifies which phases belong to each completed milestone, shows a dry-run summary, and moves directories on confirmation. - + @@ -27,7 +27,7 @@ Extract each milestone version (e.g., v1.0, v1.1, v2.0). Check which milestone archive dirs already exist: ```bash -ls -d .planning/milestones/v*-phases 2>/dev/null +ls -d .planning/milestones/v*-phases 2>/dev/null || true ``` Filter to milestones that do NOT already have a `-phases` archive directory. @@ -55,7 +55,7 @@ Extract phase numbers and names from the archived roadmap (e.g., Phase 1: Founda Check which of those phase directories still exist in `.planning/phases/`: ```bash -ls -d .planning/phases/*/ 2>/dev/null +ls -d .planning/phases/*/ 2>/dev/null || true ``` Match phase directories to milestone membership. Only include directories that still exist in `.planning/phases/`. diff --git a/gsd-opencode/get-shit-done/workflows/complete-milestone.md b/gsd-opencode/get-shit-done/workflows/complete-milestone.md index bbe9a6d..5186887 100644 --- a/gsd-opencode/get-shit-done/workflows/complete-milestone.md +++ b/gsd-opencode/get-shit-done/workflows/complete-milestone.md @@ -1,8 +1,8 @@ - + Mark a shipped version (v1.0, v1.1, v2.0) as complete. Creates historical record in MILESTONES.md, performs full PROJECT.md evolution review, reorganizes ROADMAP.md with milestone groupings, and tags the release in git. - + @@ -24,6 +24,8 @@ When a milestone completes: 4. Delete REQUIREMENTS.md (fresh one for next milestone) 5. Perform full PROJECT.md evolution review 6. Offer to create next milestone inline +7. Archive UI artifacts (`*-UI-SPEC.md`, `*-UI-REVIEW.md`) alongside other phase documents +8. Clean up `.planning/ui-reviews/` screenshot files (binary assets, never archived) **Context Efficiency:** Archives keep ROADMAP.md constant-size and REQUIREMENTS.md milestone-scoped. @@ -88,7 +90,7 @@ If user selects "Proceed anyway": note incomplete requirements in MILESTONES.md ```bash -cat .planning/config.json 2>/dev/null +cat .planning/config.json 2>/dev/null || true ``` @@ -127,7 +129,7 @@ Calculate milestone statistics: ```bash git log --oneline --grep="feat(" | head -20 git diff --stat FIRST_COMMIT..LAST_COMMIT | tail -1 -find . -name "*.swift" -o -name "*.ts" -o -name "*.py" | xargs wc -l 2>/dev/null +find . -name "*.swift" -o -name "*.ts" -o -name "*.py" | xargs wc -l 2>/dev/null || true git log --format="%ai" FIRST_COMMIT | tail -1 git log --format="%ai" LAST_COMMIT | head -1 ``` @@ -154,7 +156,8 @@ Extract one-liners from SUMMARY.md files using summary-extract: ```bash # For each phase in milestone, extract one-liner for summary in .planning/phases/*-*/*-SUMMARY.md; do - node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" summary-extract "$summary" --fields one_liner | jq -r '.one_liner' + [ -e "$summary" ] || continue + node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" summary-extract "$summary" --fields one_liner --pick one_liner done ``` @@ -444,7 +447,7 @@ rm .planning/REQUIREMENTS.md Check for existing retrospective: ```bash -ls .planning/RETROSPECTIVE.md 2>/dev/null +ls .planning/RETROSPECTIVE.md 2>/dev/null || true ``` **If exists:** read the file, append new milestone section before the "## Cross-Milestone Trends" section. diff --git a/gsd-opencode/get-shit-done/workflows/diagnose-issues.md b/gsd-opencode/get-shit-done/workflows/diagnose-issues.md index 2e9c352..df0313e 100644 --- a/gsd-opencode/get-shit-done/workflows/diagnose-issues.md +++ b/gsd-opencode/get-shit-done/workflows/diagnose-issues.md @@ -1,10 +1,15 @@ - + Orchestrate parallel debug agents to investigate UAT gaps and find root causes. After UAT finds gaps, spawn one debug agent per gap. Each agent investigates autonomously with symptoms pre-filled from UAT. Collect root causes, update UAT.md gaps with diagnosis, then hand off to plan-phase --gaps with actual diagnoses. Orchestrator stays lean: parse gaps, spawn agents, collect results, update UAT. - + + + +Valid GSD subagent types (use exact names — do not fall back to 'general'): +- gsd-debugger — Diagnoses and fixes issues + DEBUG_DIR=.planning/debug @@ -73,14 +78,21 @@ This runs in parallel - all gaps investigated simultaneously. +**Load agent skills:** + +```bash +AGENT_SKILLS_DEBUGGER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-debugger 2>/dev/null) +``` + **Spawn debug agents in parallel:** For each gap, fill the debug-subagent-prompt template and spawn: ``` task( - prompt=filled_debug_subagent_prompt + "\n\n\n- {phase_dir}/{phase_num}-UAT.md\n- .planning/STATE.md\n", + prompt=filled_debug_subagent_prompt + "\n\n\n- {phase_dir}/{phase_num}-UAT.md\n- .planning/STATE.md\n\n${AGENT_SKILLS_DEBUGGER}", subagent_type="gsd-debugger", + isolation="worktree", description="Debug: {truth_short}" ) ``` diff --git a/gsd-opencode/get-shit-done/workflows/discovery-phase.md b/gsd-opencode/get-shit-done/workflows/discovery-phase.md index e1321d5..76bd0cd 100644 --- a/gsd-opencode/get-shit-done/workflows/discovery-phase.md +++ b/gsd-opencode/get-shit-done/workflows/discovery-phase.md @@ -1,11 +1,11 @@ - + Execute discovery at the appropriate depth level. Produces DISCOVERY.md (for Level 2-3) that informs PLAN.md creation. Called from plan-phase.md's mandatory_discovery step with a depth parameter. NOTE: For comprehensive ecosystem research ("how do experts build this"), use /gsd-research-phase instead, which produces RESEARCH.md. - + **This workflow supports three depth levels:** @@ -93,7 +93,7 @@ For: Choosing between options, new external integration. ``` For each library/framework: - - mcp__context7__resolve-library-id + - mcp__context7__resolve-library-id - mcp__context7__get-library-docs (mode: "code" for API, "info" for concepts) ``` diff --git a/gsd-opencode/get-shit-done/workflows/discuss-phase-assumptions.md b/gsd-opencode/get-shit-done/workflows/discuss-phase-assumptions.md new file mode 100644 index 0000000..5b07038 --- /dev/null +++ b/gsd-opencode/get-shit-done/workflows/discuss-phase-assumptions.md @@ -0,0 +1,653 @@ + +Extract implementation decisions that downstream agents need — using codebase-first analysis +and assumption surfacing instead of interview-style questioning. + +You are a thinking partner, not an interviewer. Analyze the codebase deeply, surface what you +believe based on evidence, and ask the user only to correct what's wrong. + + + +Valid GSD subagent types (use exact names — do not fall back to 'general'): +- gsd-assumptions-analyzer — Analyzes codebase to surface implementation assumptions + + + +**CONTEXT.md feeds into:** + +1. **gsd-phase-researcher** — Reads CONTEXT.md to know WHAT to research +2. **gsd-planner** — Reads CONTEXT.md to know WHAT decisions are locked + +**Your job:** Capture decisions clearly enough that downstream agents can act on them +without asking the user again. Output is identical to discuss mode — same CONTEXT.md format. + + + +**Assumptions mode philosophy:** + +The user is a visionary, not a codebase archaeologist. They need enough context to evaluate +whether your assumptions match their intent — not to answer questions you could figure out +by reading the code. + +- read the codebase FIRST, form opinions SECOND, ask ONLY about what's genuinely unclear +- Every assumption must cite evidence (file paths, patterns found) +- Every assumption must state consequences if wrong +- Minimize user interactions: ~2-4 corrections vs ~15-20 questions + + + +**CRITICAL: No scope creep.** + +The phase boundary comes from ROADMAP.md and is FIXED. Discussion clarifies HOW to implement +what's scoped, never WHETHER to add new capabilities. + +When user suggests scope creep: +"[Feature X] would be a new capability — that's its own phase. +Want me to note it for the roadmap backlog? For now, let's focus on [phase domain]." + +Capture the idea in "Deferred Ideas". Don't lose it, don't act on it. + + + +**IMPORTANT: Answer validation** — After every question call, check if the response +is empty or whitespace-only. If so: +1. Retry the question once with the same parameters +2. If still empty, present the options as a plain-text numbered list + +**Text mode (`workflow.text_mode: true` in config or `--text` flag):** +When text mode is active, do not use question at all. Present every question as a +plain-text numbered list and ask the user to type their choice number. + + + + + +Phase number from argument (required). + +```bash +INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE}") +if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +AGENT_SKILLS_ANALYZER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-assumptions-analyzer 2>/dev/null) +``` + +Parse JSON for: `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, +`phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `has_verification`, +`plan_count`, `roadmap_exists`, `planning_exists`. + +**If `phase_found` is false:** +``` +Phase [X] not found in roadmap. + +Use /gsd-progress to see available phases. +``` +Exit workflow. + +**If `phase_found` is true:** Continue to check_existing. + +**Auto mode** — If `--auto` is present in ARGUMENTS: +- In `check_existing`: auto-select "Update it" (if context exists) or continue without prompting +- In `present_assumptions`: skip confirmation gate, proceed directly to write CONTEXT.md +- In `correct_assumptions`: auto-select recommended option for each correction +- Log each auto-selected choice inline +- After completion, auto-advance to plan-phase + + + +Check if CONTEXT.md already exists using `has_context` from init. + +```bash +ls ${phase_dir}/*-CONTEXT.md 2>/dev/null || true +``` + +**If exists:** + +**If `--auto`:** Auto-select "Update it". Log: `[auto] Context exists — updating with assumption-based analysis.` + +**Otherwise:** Use question: +- header: "Context" +- question: "Phase [X] already has context. What do you want to do?" +- options: + - "Update it" — Re-analyze codebase and refresh assumptions + - "View it" — Show me what's there + - "Skip" — Use existing context as-is + +If "Update": Load existing, continue to load_prior_context +If "View": Display CONTEXT.md, then offer update/skip +If "Skip": Exit workflow + +**If doesn't exist:** + +Check `has_plans` and `plan_count` from init. **If `has_plans` is true:** + +**If `--auto`:** Auto-select "Continue and replan after". Log: `[auto] Plans exist — continuing with assumption analysis, will replan after.` + +**Otherwise:** Use question: +- header: "Plans exist" +- question: "Phase [X] already has {plan_count} plan(s) created without user context. Your decisions here won't affect existing plans unless you replan." +- options: + - "Continue and replan after" + - "View existing plans" + - "Cancel" + +If "Continue and replan after": Continue to load_prior_context. +If "View existing plans": Display plan files, then offer "Continue" / "Cancel". +If "Cancel": Exit workflow. + +**If `has_plans` is false:** Continue to load_prior_context. + + + +read project-level and prior phase context to avoid re-asking decided questions. + +**Step 1: read project-level files** +```bash +cat .planning/PROJECT.md 2>/dev/null || true +cat .planning/REQUIREMENTS.md 2>/dev/null || true +cat .planning/STATE.md 2>/dev/null || true +``` + +Extract from these: +- **PROJECT.md** — Vision, principles, non-negotiables, user preferences +- **REQUIREMENTS.md** — Acceptance criteria, constraints +- **STATE.md** — Current progress, any flags + +**Step 2: read all prior CONTEXT.md files** +```bash +(find .planning/phases -name "*-CONTEXT.md" 2>/dev/null || true) | sort +``` + +For each CONTEXT.md where phase number < current phase: +- read the `` section — these are locked preferences +- read `` — particular references or "I want it like X" moments +- Note patterns (e.g., "user consistently prefers minimal UI") + +**Step 3: Build internal `` context** + +Structure the extracted information for use in assumption generation. + +**If no prior context exists:** Continue without — expected for early phases. + + + +Check if any pending todos are relevant to this phase's scope. + +```bash +TODO_MATCHES=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" todo match-phase "${PHASE_NUMBER}") +``` + +Parse JSON for: `todo_count`, `matches[]`. + +**If `todo_count` is 0:** Skip silently. + +**If matches found:** Present matched todos, use question (multiSelect) to fold relevant ones into scope. + +**For selected (folded) todos:** Store as `` for CONTEXT.md `` section. +**For unselected:** Store as `` for CONTEXT.md `` section. + +**Auto mode (`--auto`):** Fold all todos with score >= 0.4 automatically. Log the selection. + + + +Lightweight scan of existing code to inform assumption generation. + +**Step 1: Check for existing codebase maps** +```bash +ls .planning/codebase/*.md 2>/dev/null || true +``` + +**If codebase maps exist:** read relevant ones (CONVENTIONS.md, STRUCTURE.md, STACK.md). Extract reusable components, patterns, integration points. Skip to Step 3. + +**Step 2: If no codebase maps, do targeted grep** + +Extract key terms from phase goal, search for related files. + +```bash +grep -rl "{term1}\|{term2}" src/ app/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -10 +``` + +read the 3-5 most relevant files. + +**Step 3: Build internal ``** + +Identify reusable assets, established patterns, integration points, and creative options. Store internally for use in deep_codebase_analysis. + + + +Spawn a `gsd-assumptions-analyzer` agent to deeply analyze the codebase for this phase. This +keeps raw file contents out of the main context window, protecting token budget. + +**Resolve calibration tier (if USER-PROFILE.md exists):** + +```bash +PROFILE_PATH="$HOME/.config/opencode/get-shit-done/USER-PROFILE.md" +``` + +If file exists at PROFILE_PATH: +- Priority 1: read config.json > preferences.vendor_philosophy (project-level override) +- Priority 2: read USER-PROFILE.md Vendor Choices/Philosophy rating (global) +- Priority 3: Default to "standard" + +Map to calibration tier: +- conservative OR thorough-evaluator → full_maturity (more alternatives, detailed evidence) +- opinionated → minimal_decisive (fewer alternatives, decisive recommendations) +- pragmatic-fast OR any other value → standard + +If no USER-PROFILE.md: calibration_tier = "standard" + +**Spawn Explore subagent:** + +``` +task(subagent_type="gsd-assumptions-analyzer", prompt=""" +Analyze the codebase for Phase {PHASE}: {phase_name}. + +Phase goal: {roadmap_description} +Prior decisions: {prior_decisions_summary} +Codebase scout hints: {codebase_context_summary} +Calibration: {calibration_tier} + +Your job: +1. read ROADMAP.md phase {PHASE} description +2. read any prior CONTEXT.md files from earlier phases +3. glob/grep for files related to: {phase_relevant_terms} +4. read 5-15 most relevant source files +5. Return structured assumptions + +## Output Format + +Return EXACTLY this structure: + +## Assumptions + +### [Area Name] (e.g., "Technical Approach") +- **Assumption:** [Decision statement] + - **Why this way:** [Evidence from codebase — cite file paths] + - **If wrong:** [Concrete consequence of this being wrong] + - **Confidence:** Confident | Likely | Unclear + +(3-5 areas, calibrated by tier: +- full_maturity: 3-5 areas, 2-3 alternatives per Likely/Unclear item +- standard: 3-4 areas, 2 alternatives per Likely/Unclear item +- minimal_decisive: 2-3 areas, decisive single recommendation per item) + +## Needs External Research +[Topics where codebase alone is insufficient — library version compatibility, +ecosystem best practices, etc. Leave empty if codebase provides enough evidence.] + +${AGENT_SKILLS_ANALYZER} +""") +``` + +Parse the subagent's response. Extract: +- `assumptions[]` — each with area, statement, evidence, consequence, confidence +- `needs_research[]` — topics requiring external research (may be empty) + +**Initialize canonical refs accumulator:** +- Source 1: Copy `Canonical refs:` from ROADMAP.md for this phase, expand to full paths +- Source 2: Check REQUIREMENTS.md and PROJECT.md for specs/ADRs referenced +- Source 3: Add any docs referenced in codebase scout results + + + +**Skip if:** `needs_research` from deep_codebase_analysis is empty. + +If research topics were flagged, spawn a general research agent: + +``` +task(subagent_type="general", prompt=""" +Research the following topics for Phase {PHASE}: {phase_name}. + +Topics needing research: +{needs_research_content} + +For each topic, return: +- **Finding:** [What you learned] +- **Source:** [URL or library docs reference] +- **Confidence impact:** [Which assumption this resolves and to what confidence level] + +Use Context7 (resolve-library-id then query-docs) for library-specific questions. +Use websearch for ecosystem/best-practice questions. +""") +``` + +Merge findings back into assumptions: +- Update confidence levels where research resolves ambiguity +- Add source attribution to affected assumptions +- Store research findings for DISCUSSION-LOG.md + +**If no gaps flagged:** Skip entirely. Most phases will skip this step. + + + +Display all assumptions grouped by area with confidence badges. + +**Format for display:** + +``` +## Phase {PHASE}: {phase_name} — Assumptions + +Based on codebase analysis, here's what I'd go with: + +### {Area Name} +{Confidence badge} **{Assumption statement}** +↳ Evidence: {file paths cited} +↳ If wrong: {consequence} + +### {Area Name 2} +... + +[If external research was done:] +### External Research Applied +- {Topic}: {Finding} (Source: {URL}) +``` + +**If `--auto`:** +- If all assumptions are Confident or Likely: log assumptions, skip to write_context. + Log: `[auto] All assumptions Confident/Likely — proceeding to context capture.` +- If any assumptions are Unclear: log a warning, auto-select recommended alternative for + each Unclear item. Log: `[auto] {N} Unclear assumptions auto-resolved with recommended defaults.` + Proceed to write_context. + +**Otherwise:** Use question: +- header: "Assumptions" +- question: "These all look right?" +- options: + - "Yes, proceed" — write CONTEXT.md with these assumptions as decisions + - "Let me correct some" — Select which assumptions to change + +**If "Yes, proceed":** Skip to write_context. +**If "Let me correct some":** Continue to correct_assumptions. + + + +The assumptions are already displayed above from present_assumptions. + +Present a multiSelect where each option's label is the assumption statement and description +is the "If wrong" consequence: + +Use question (multiSelect): +- header: "Corrections" +- question: "Which assumptions need correcting?" +- options: [one per assumption, label = assumption statement, description = "If wrong: {consequence}"] + +For each selected correction, ask ONE focused question: + +Use question: +- header: "{Area Name}" +- question: "What should we do instead for: {assumption statement}?" +- options: [2-3 concrete alternatives describing user-visible outcomes, recommended option first] + +Record each correction: +- Original assumption +- User's chosen alternative +- Reason (if provided via "Other" free text) + +After all corrections processed, continue to write_context with updated assumptions. + +**Auto mode:** Should not reach this step (--auto skips from present_assumptions). + + + +Create phase directory if needed. write CONTEXT.md using the standard 6-section format. + +**File:** `${phase_dir}/${padded_phase}-CONTEXT.md` + +Map assumptions to CONTEXT.md sections: +- Assumptions → `` (each assumption becomes a locked decision: D-01, D-02, etc.) +- Corrections → override the original assumption in `` +- Areas where all assumptions were Confident → marked as locked decisions +- Areas with corrections → include user's chosen alternative as the decision +- Folded todos → included in `` under "### Folded Todos" + +```markdown +# Phase {PHASE}: {phase_name} - Context + +**Gathered:** {date} (assumptions mode) +**Status:** Ready for planning + + +## Phase Boundary + +{Domain boundary from ROADMAP.md — clear statement of scope anchor} + + + +## Implementation Decisions + +### {Area Name 1} +- **D-01:** {Decision — from assumption or correction} +- **D-02:** {Decision} + +### {Area Name 2} +- **D-03:** {Decision} + +### OpenCode's Discretion +{Any assumptions where the user confirmed "you decide" or left as-is with Likely confidence} + +### Folded Todos +{If any todos were folded into scope} + + + +## Canonical References + +**Downstream agents MUST read these before planning or implementing.** + +{Accumulated canonical refs from analyze step — full relative paths} + +[If no external specs: "No external specs — requirements fully captured in decisions above"] + + + +## Existing Code Insights + +### Reusable Assets +{From codebase scout + Explore subagent findings} + +### Established Patterns +{Patterns that constrain/enable this phase} + +### Integration Points +{Where new code connects to existing system} + + + +## Specific Ideas + +{Any particular references from corrections or user input} + +[If none: "No specific requirements — open to standard approaches"] + + + +## Deferred Ideas + +{Ideas mentioned during corrections that are out of scope} + +### Reviewed Todos (not folded) +{Todos reviewed but not folded — with reason} + +[If none: "None — analysis stayed within phase scope"] + +``` + +write file. + + + +write audit trail of assumptions and corrections. + +**File:** `${phase_dir}/${padded_phase}-DISCUSSION-LOG.md` + +```markdown +# Phase {PHASE}: {phase_name} - Discussion Log (Assumptions Mode) + +> **Audit trail only.** Do not use as input to planning, research, or execution agents. +> Decisions captured in CONTEXT.md — this log preserves the analysis. + +**Date:** {ISO date} +**Phase:** {padded_phase}-{phase_name} +**Mode:** assumptions +**Areas analyzed:** {comma-separated area names} + +## Assumptions Presented + +### {Area Name} +| Assumption | Confidence | Evidence | +|------------|-----------|----------| +| {Statement} | {Confident/Likely/Unclear} | {file paths} | + +{Repeat for each area} + +## Corrections Made + +{If corrections were made:} + +### {Area Name} +- **Original assumption:** {what OpenCode assumed} +- **User correction:** {what the user chose instead} +- **Reason:** {user's rationale, if provided} + +{If no corrections: "No corrections — all assumptions confirmed."} + +## Auto-Resolved + +{If --auto and Unclear items existed:} +- {Assumption}: auto-selected {recommended option} + +{If not applicable: omit this section} + +## External Research + +{If research was performed:} +- {Topic}: {Finding} (Source: {URL}) + +{If no research: omit this section} +``` + +write file. + + + +Commit phase context and discussion log: + +```bash +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs(${padded_phase}): capture phase context (assumptions mode)" --files "${phase_dir}/${padded_phase}-CONTEXT.md" "${phase_dir}/${padded_phase}-DISCUSSION-LOG.md" +``` + +Confirm: "Committed: docs(${padded_phase}): capture phase context (assumptions mode)" + + + +Update STATE.md with session info: + +```bash +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" state record-session \ + --stopped-at "Phase ${PHASE} context gathered (assumptions mode)" \ + --resume-file "${phase_dir}/${padded_phase}-CONTEXT.md" +``` + +Commit STATE.md: + +```bash +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs(state): record phase ${PHASE} context session" --files .planning/STATE.md +``` + + + +Present summary and next steps: + +``` +Created: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md + +## Decisions Captured (Assumptions Mode) + +### {Area Name} +- {Key decision} (from assumption / corrected) + +{Repeat per area} + +[If corrections were made:] +## Corrections Applied +- {Area}: {original} → {corrected} + +[If deferred ideas exist:] +## Noted for Later +- {Deferred idea} — future phase + +--- + +## ▶ Next Up + +**Phase ${PHASE}: {phase_name}** — {Goal from ROADMAP.md} + +`/gsd-plan-phase ${PHASE}` + +*`/new` first → fresh context window* + +--- + +**Also available:** +- `/gsd-plan-phase ${PHASE} --skip-research` — plan without research +- `/gsd-ui-phase ${PHASE}` — generate UI design contract (if frontend work) +- Review/edit CONTEXT.md before continuing + +--- +``` + + + +Check for auto-advance trigger: + +1. Parse `--auto` flag from $ARGUMENTS +2. Sync chain flag: + ```bash + if [[ ! "$ARGUMENTS" =~ --auto ]]; then + node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-set workflow._auto_chain_active false 2>/dev/null + fi + ``` +3. read chain flag and user preference: + ```bash + AUTO_CHAIN=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow._auto_chain_active 2>/dev/null || echo "false") + AUTO_CFG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.auto_advance 2>/dev/null || echo "false") + ``` + +**If `--auto` flag present AND `AUTO_CHAIN` is not true:** +```bash +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-set workflow._auto_chain_active true +``` + +**If `--auto` flag present OR `AUTO_CHAIN` is true OR `AUTO_CFG` is true:** + +Display banner: +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► AUTO-ADVANCING TO PLAN +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Context captured (assumptions mode). Launching plan-phase... +``` + +Launch: `skill(skill="gsd-plan-phase", args="${PHASE} --auto")` + +Handle return: PHASE COMPLETE / PLANNING COMPLETE / INCONCLUSIVE / GAPS FOUND +(identical handling to discuss-phase.md auto_advance step) + +**If neither `--auto` nor config enabled:** +Route to confirm_creation step. + + + + + +- Phase validated against roadmap +- Prior context loaded (no re-asking decided questions) +- Codebase deeply analyzed via Explore subagent (5-15 files read) +- Assumptions surfaced with evidence and confidence levels +- User confirmed or corrected assumptions (~2-4 interactions max) +- Scope creep redirected to deferred ideas +- CONTEXT.md captures actual decisions (identical format to discuss mode) +- CONTEXT.md includes canonical_refs with full file paths (MANDATORY) +- CONTEXT.md includes code_context from codebase analysis +- DISCUSSION-LOG.md records assumptions and corrections as audit trail +- STATE.md updated with session info +- User knows next steps + diff --git a/gsd-opencode/get-shit-done/workflows/discuss-phase.md b/gsd-opencode/get-shit-done/workflows/discuss-phase.md index 94875a4..e999a2c 100644 --- a/gsd-opencode/get-shit-done/workflows/discuss-phase.md +++ b/gsd-opencode/get-shit-done/workflows/discuss-phase.md @@ -1,8 +1,8 @@ - + Extract implementation decisions that downstream agents need. Analyze the phase to identify gray areas, let the user choose what to discuss, then deep-dive each selected area until satisfied. You are a thinking partner, not an interviewer. The user is the visionary — you are the builder. Your job is to capture decisions that will guide research and planning, not to figure out implementation yourself. - + **CONTEXT.md feeds into:** @@ -105,6 +105,25 @@ Phase: "API documentation" - Scope (roadmap defines this) + +**IMPORTANT: Answer validation** — After every question call, check if the response is empty or whitespace-only. If so: +1. Retry the question once with the same parameters +2. If still empty, present the options as a plain-text numbered list and ask the user to type their choice number +Never proceed with an empty answer. + +**Text mode (`workflow.text_mode: true` in config or `--text` flag):** +When text mode is active, **do not use question at all**. Instead, present every +question as a plain-text numbered list and ask the user to type their choice number. +This is required for OpenCode remote sessions (`/rc` mode) where the OpenCode App +cannot forward TUI menu selections back to the host. + +Enable text mode: +- Per-session: pass `--text` flag to any command (e.g., `/gsd-discuss-phase --text`) +- Per-project: `gsd-tools config-set workflow.text_mode true` + +Text mode applies to ALL workflows in the session, not just discuss-phase. + + **Express path available:** If you already have a PRD or acceptance criteria document, use `/gsd-plan-phase {phase} --prd path/to/prd.md` to skip this discussion and go straight to planning. @@ -115,6 +134,7 @@ Phase number from argument (required). ```bash INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE}") if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +AGENT_SKILLS_ADVISOR=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-advisor 2>/dev/null) ``` Parse JSON for: `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `has_verification`, `plan_count`, `roadmap_exists`, `planning_exists`. @@ -123,22 +143,32 @@ Parse JSON for: `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phas ``` Phase [X] not found in roadmap. -Use /gsd-progress to see available phases. +Use /gsd-progress ${GSD_WS} to see available phases. ``` Exit workflow. **If `phase_found` is true:** Continue to check_existing. + +**Auto mode** — If `--auto` is present in ARGUMENTS: +- In `check_existing`: auto-select "Skip" (if context exists) or continue without prompting (if no context/plans) +- In `present_gray_areas`: auto-select ALL gray areas without asking the user +- In `discuss_areas`: for each discussion question, choose the recommended option (first option, or the one marked "recommended") without using question +- Log each auto-selected choice inline so the user can review decisions in the context file +- After discussion completes, auto-advance to plan-phase (existing behavior) Check if CONTEXT.md already exists using `has_context` from init. ```bash -ls ${phase_dir}/*-CONTEXT.md 2>/dev/null +ls ${phase_dir}/*-CONTEXT.md 2>/dev/null || true ``` **If exists:** -Use question: + +**If `--auto`:** Auto-select "Update it" — load existing context and continue to analyze_phase. Log: `[auto] Context exists — updating with auto-selected decisions.` + +**Otherwise:** Use question: - header: "Context" - question: "Phase [X] already has context. What do you want to do?" - options: @@ -154,11 +184,13 @@ If "Skip": Exit workflow Check `has_plans` and `plan_count` from init. **If `has_plans` is true:** -Use question: +**If `--auto`:** Auto-select "Continue and replan after". Log: `[auto] Plans exist — continuing with context capture, will replan after.` + +**Otherwise:** Use question: - header: "Plans exist" - question: "Phase [X] already has {plan_count} plan(s) created without user context. Your decisions here won't affect existing plans unless you replan." - options: - - "Continue and replan after" — Capture context, then run /gsd-plan-phase {X} to replan + - "Continue and replan after" — Capture context, then run /gsd-plan-phase {X} ${GSD_WS} to replan - "View existing plans" — Show plans before deciding - "Cancel" — Skip discuss-phase @@ -175,9 +207,9 @@ read project-level and prior phase context to avoid re-asking decided questions **Step 1: read project-level files** ```bash # Core project files -cat .planning/PROJECT.md 2>/dev/null -cat .planning/REQUIREMENTS.md 2>/dev/null -cat .planning/STATE.md 2>/dev/null +cat .planning/PROJECT.md 2>/dev/null || true +cat .planning/REQUIREMENTS.md 2>/dev/null || true +cat .planning/STATE.md 2>/dev/null || true ``` Extract from these: @@ -188,7 +220,7 @@ Extract from these: **Step 2: read all prior CONTEXT.md files** ```bash # Find all CONTEXT.md files from phases before current -find .planning/phases -name "*-CONTEXT.md" 2>/dev/null | sort +(find .planning/phases -name "*-CONTEXT.md" 2>/dev/null || true) | sort ``` For each CONTEXT.md where phase number < current phase: @@ -223,12 +255,53 @@ Structure the extracted information: **If no prior context exists:** Continue without — this is expected for early phases. + +Check if any pending todos are relevant to this phase's scope. Surfaces backlog items that might otherwise be missed. + +**Load and match todos:** +```bash +TODO_MATCHES=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" todo match-phase "${PHASE_NUMBER}") +``` + +Parse JSON for: `todo_count`, `matches[]` (each with `file`, `title`, `area`, `score`, `reasons`). + +**If `todo_count` is 0 or `matches` is empty:** Skip silently — no workflow slowdown. + +**If matches found:** + +Present matched todos to the user. Show each match with its title, area, and why it matched: + +``` +📋 Found {N} pending todo(s) that may be relevant to Phase {X}: + +{For each match:} +- **{title}** (area: {area}, relevance: {score}) — matched on {reasons} +``` + +Use question (multiSelect) asking which todos to fold into this phase's scope: + +``` +Which of these todos should be folded into Phase {X} scope? +(Select any that apply, or none to skip) +``` + +**For selected (folded) todos:** +- Store internally as `` for inclusion in CONTEXT.md `` section +- These become additional scope items that downstream agents (researcher, planner) will see + +**For unselected (reviewed but not folded) todos:** +- Store internally as `` for inclusion in CONTEXT.md `` section +- This prevents future phases from re-surfacing the same todos as "missed" + +**Auto mode (`--auto`):** Fold all todos with score >= 0.4 automatically. Log the selection. + + Lightweight scan of existing code to inform gray area identification and discussion. Uses ~10% context — acceptable for an interactive session. **Step 1: Check for existing codebase maps** ```bash -ls .planning/codebase/*.md 2>/dev/null +ls .planning/codebase/*.md 2>/dev/null || true ``` **If codebase maps exist:** read the most relevant ones (CONVENTIONS.md, STRUCTURE.md, STACK.md based on phase type). Extract: @@ -244,12 +317,12 @@ Extract key terms from the phase goal (e.g., "feed" → "post", "card", "list"; ```bash # Find files related to phase goal terms -grep -rl "{term1}\|{term2}" src/ app/ --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" 2>/dev/null | head -10 +grep -rl "{term1}\|{term2}" src/ app/ --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" 2>/dev/null | head -10 || true # Find existing components/hooks -ls src/components/ 2>/dev/null -ls src/hooks/ 2>/dev/null -ls src/lib/ src/utils/ 2>/dev/null +ls src/components/ 2>/dev/null || true +ls src/hooks/ 2>/dev/null || true +ls src/lib/ src/utils/ 2>/dev/null || true ``` read the 3-5 most relevant files to understand existing patterns. @@ -272,6 +345,15 @@ Analyze the phase to identify gray areas worth discussing. **Use both `prior_dec 1. **Domain boundary** — What capability is this phase delivering? State it clearly. +1b. **Initialize canonical refs accumulator** — Start building the `` list for CONTEXT.md. This accumulates throughout the entire discussion, not just this step. + + **Source 1 (now):** Copy `Canonical refs:` from ROADMAP.md for this phase. Expand each to a full relative path. + **Source 2 (now):** Check REQUIREMENTS.md and PROJECT.md for any specs/ADRs referenced for this phase. + **Source 3 (scout_codebase):** If existing code references docs (e.g., comments citing ADRs), add those. + **Source 4 (discuss_areas):** When the user says "read X", "check Y", or references any doc/spec/ADR during discussion — add it immediately. These are often the MOST important refs because they represent docs the user specifically wants followed. + + This list is MANDATORY in CONTEXT.md. Every ref must have a full relative path so downstream agents can read it directly. If no external docs exist, note that explicitly. + 2. **Check prior decisions** — Before generating gray areas, check if any were already decided: - Scan `` for relevant choices (e.g., "Ctrl+C only, no single-key shortcuts") - These are **pre-answered** — don't re-ask unless this phase has conflicting needs @@ -281,6 +363,33 @@ Analyze the phase to identify gray areas worth discussing. **Use both `prior_dec 4. **Skip assessment** — If no meaningful gray areas exist (pure infrastructure, clear-cut implementation, or all already decided in prior phases), the phase may not need discussion. +**Advisor Mode Detection:** + +Check if advisor mode should activate: + +1. Check for USER-PROFILE.md: + ```bash + PROFILE_PATH="$HOME/.config/opencode/get-shit-done/USER-PROFILE.md" + ``` + ADVISOR_MODE = file exists at PROFILE_PATH → true, otherwise → false + +2. If ADVISOR_MODE is true, resolve vendor_philosophy calibration tier: + - Priority 1: read config.json > preferences.vendor_philosophy (project-level override) + - Priority 2: read USER-PROFILE.md Vendor Choices/Philosophy rating (global) + - Priority 3: Default to "standard" if neither has a value or value is UNSCORED + + Map to calibration tier: + - conservative OR thorough-evaluator → full_maturity + - opinionated → minimal_decisive + - pragmatic-fast OR any other value OR empty → standard + +3. Resolve model for advisor agents: + ```bash + ADVISOR_MODEL=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" resolve-model gsd-advisor-researcher --raw) + ``` + +If ADVISOR_MODE is false, skip all advisor-specific steps — workflow proceeds with existing conversational flow unchanged. + **Output your analysis internally, then present to user.** Example analysis for "Post Feed" phase (with code and prior context): @@ -314,7 +423,9 @@ We'll clarify HOW to implement this. - [Decision from Phase M that applies here] ``` -**Then use question (multiSelect: true):** +**If `--auto`:** Auto-select ALL gray areas. Log: `[auto] Selected all gray areas: [list area names].` Skip the question below and continue directly to discuss_areas with all areas selected. + +**Otherwise, use question (multiSelect: true):** - header: "Discuss" - question: "Which areas do you want to discuss for [phase name]?" - options: Generate 3-4 phase-specific gray areas, each with: @@ -368,15 +479,168 @@ For "Organize photo library" (organization task): ☐ Folder structure — Flat, nested by year, or by category? ``` -Continue to discuss_areas with selected areas. +Continue to discuss_areas with selected areas (or advisor_research if ADVISOR_MODE is true). + + + +**Advisor Research** (only when ADVISOR_MODE is true) + +After user selects gray areas in present_gray_areas, spawn parallel research agents. + +1. Display brief status: "Researching {N} areas..." + +2. For EACH user-selected gray area, spawn a task() in parallel: + + task( + prompt="First, read @$HOME/.config/opencode/agents/gsd-advisor-researcher.md for your role and instructions. + + {area_name}: {area_description from gray area identification} + {phase_goal and description from ROADMAP.md} + {project name and brief description from PROJECT.md} + {resolved calibration tier: full_maturity | standard | minimal_decisive} + + Research this gray area and return a structured comparison table with rationale. + ${AGENT_SKILLS_ADVISOR}", + subagent_type="general", + model="{ADVISOR_MODEL}", + description="Research: {area_name}" + ) + + All task() calls spawn simultaneously — do NOT wait for one before starting the next. + +3. After ALL agents return, SYNTHESIZE results before presenting: + For each agent's return: + a. Parse the markdown comparison table and rationale paragraph + b. Verify all 5 columns present (Option | Pros | Cons | Complexity | Recommendation) — fill any missing columns rather than showing broken table + c. Verify option count matches calibration tier: + - full_maturity: 3-5 options acceptable + - standard: 2-4 options acceptable + - minimal_decisive: 1-2 options acceptable + If agent returned too many, trim least viable. If too few, accept as-is. + d. Rewrite rationale paragraph to weave in project context and ongoing discussion context that the agent did not have access to + e. If agent returned only 1 option, convert from table format to direct recommendation: "Standard approach for {area}: {option}. {rationale}" + +4. Store synthesized tables for use in discuss_areas. + +**If ADVISOR_MODE is false:** Skip this step entirely — proceed directly from present_gray_areas to discuss_areas. +Discuss each selected area with the user. Flow depends on advisor mode. + +**If ADVISOR_MODE is true:** + +Table-first discussion flow — present research-backed comparison tables, then capture user picks. + +**For each selected area:** + +1. **Present the synthesized comparison table + rationale paragraph** (from advisor_research step) + +2. **Use question:** + - header: "{area_name}" + - question: "Which approach for {area_name}?" + - options: Extract from the table's Option column (question adds "Other" automatically) + +3. **Record the user's selection:** + - If user picks from table options → record as locked decision for that area + - If user picks "Other" → receive their input, reflect it back for confirmation, record + +4. **After recording pick, OpenCode decides whether follow-up questions are needed:** + - If the pick has ambiguity that would affect downstream planning → ask 1-2 targeted follow-up questions using question + - If the pick is clear and self-contained → move to next area + - Do NOT ask the standard 4 questions — the table already provided the context + +5. **After all areas processed:** + - header: "Done" + - question: "That covers [list areas]. Ready to create context?" + - options: "Create context" / "Revisit an area" + +**Scope creep handling (advisor mode):** +If user mentions something outside the phase domain: +``` +"[Feature] sounds like a new capability — that belongs in its own phase. +I'll note it as a deferred idea. + +Back to [current area]: [return to current question]" +``` + +Track deferred ideas internally. + +--- + +**If ADVISOR_MODE is false:** + For each selected area, conduct a focused discussion loop. -**Philosophy: 4 questions, then check.** +**Research-before-questions mode:** Check if `workflow.research_before_questions` is enabled in config (from init context or `.planning/config.json`). When enabled, before presenting questions for each area: +1. Do a brief web search for best practices related to the area topic +2. Summarize the top findings in 2-3 bullet points +3. Present the research alongside the question so the user can make a more informed decision + +Example with research enabled: +``` +Let's talk about [Authentication Strategy]. + +📊 Best practices research: +• OAuth 2.0 + PKCE is the current standard for SPAs (replaces implicit flow) +• Session tokens with httpOnly cookies preferred over localStorage for XSS protection +• Consider passkey/WebAuthn support — adoption is accelerating in 2025-2026 + +With that context: How should users authenticate? +``` + +When disabled (default), skip the research and present questions directly as before. + +**Text mode support:** Parse optional `--text` from `$ARGUMENTS`. +- Accept `--text` flag OR read `workflow.text_mode` from config (from init context) +- When active, replace ALL `question` calls with plain-text numbered lists +- User types a number to select, or types free text for "Other" +- This is required for OpenCode remote sessions (`/rc` mode) where TUI menus + don't work through the OpenCode App + +**Batch mode support:** Parse optional `--batch` from `$ARGUMENTS`. +- Accept `--batch`, `--batch=N`, or `--batch N` + +**Analyze mode support:** Parse optional `--analyze` from `$ARGUMENTS`. +When `--analyze` is active, before presenting each question (or question group in batch mode), provide a brief **trade-off analysis** for the decision: +- 2-3 options with pros/cons based on codebase context and common patterns +- A recommended approach with reasoning +- Known pitfalls or constraints from prior phases -Ask 4 questions per area before offering to continue or move on. Each answer often reveals the next question. +Example with `--analyze`: +``` +**Trade-off analysis: Authentication strategy** + +| Approach | Pros | Cons | +|----------|------|------| +| Session cookies | Simple, httpOnly prevents XSS | Requires CSRF protection, sticky sessions | +| JWT (stateless) | Scalable, no server state | Token size, revocation complexity | +| OAuth 2.0 + PKCE | Industry standard for SPAs | More setup, redirect flow UX | + +💡 Recommended: OAuth 2.0 + PKCE — your app has social login in requirements (REQ-04) and this aligns with the existing NextAuth setup in `src/lib/auth.ts`. + +How should users authenticate? +``` + +This gives the user context to make informed decisions without extra prompting. When `--analyze` is absent, present questions directly as before. +- Accept `--batch`, `--batch=N`, or `--batch N` +- Default to 4 questions per batch when no number is provided +- Clamp explicit sizes to 2-5 so a batch stays answerable +- If `--batch` is absent, keep the existing one-question-at-a-time flow + +**Philosophy:** stay adaptive, but let the user choose the pacing. +- Default mode: 4 single-question turns, then check whether to continue +- `--batch` mode: 1 grouped turn with 2-5 numbered questions, then check whether to continue + +Each answer (or answer set, in batch mode) should reveal the next question or next batch. + +**Auto mode (`--auto`):** For each area, OpenCode selects the recommended option (first option, or the one explicitly marked "recommended") for every question without using question. Log each auto-selected choice: +``` +[auto] [Area] — Q: "[question text]" → Selected: "[chosen option]" (recommended default) +``` +After all areas are auto-resolved, skip the "Explore more gray areas" prompt and proceed directly to write_context. + +**Interactive mode (no `--auto`):** **For each area:** @@ -385,7 +649,9 @@ Ask 4 questions per area before offering to continue or move on. Each answer oft Let's talk about [Area]. ``` -2. **Ask 4 questions using question:** +2. **Ask questions using the selected pacing:** + + **Default (no `--batch`): Ask 4 questions using question** - header: "[Area]" (max 12 chars — abbreviate if needed) - question: Specific decision for this area - options: 2-3 concrete choices (question adds "Other" automatically), with the recommended choice highlighted and brief explanation why @@ -399,12 +665,21 @@ Ask 4 questions per area before offering to continue or move on. Each answer oft - Include "You decide" as an option when reasonable — captures OpenCode discretion - **Context7 for library choices:** When a gray area involves library selection (e.g., "magic links" → query next-auth docs) or API approach decisions, use `mcp__context7__*` tools to fetch current documentation and inform the options. Don't use Context7 for every question — only when library-specific knowledge improves the options. -3. **After 4 questions, check:** + **Batch mode (`--batch`): Ask 2-5 numbered questions in one plain-text turn** + - Group closely related questions for the current area into a single message + - Keep each question concrete and answerable in one reply + - When options are helpful, include short inline choices per question rather than a separate question for every item + - After the user replies, reflect back the captured decisions, note any unanswered items, and ask only the minimum follow-up needed before moving on + - Preserve adaptiveness between batches: use the full set of answers to decide the next batch or whether the area is sufficiently clear + +3. **After the current set of questions, check:** - header: "[Area]" (max 12 chars) - - question: "More questions about [area], or move to next?" + - question: "More questions about [area], or move to next? (Remaining: [list other unvisited areas])" - options: "More questions" / "Next area" - If "More questions" → ask 4 more, then check again + When building the question text, list the remaining unvisited areas so the user knows what's ahead. For example: "More questions about Layout, or move to next? (Remaining: Loading behavior, Content ordering)" + + If "More questions" → ask another 4 single questions, or another 2-5 question batch when `--batch` is active, then check again If "Next area" → proceed to next selected area If "Other" (free text) → interpret intent: continuation phrases ("chat more", "keep going", "yes", "more") map to "More questions"; advancement phrases ("done", "move on", "next", "skip") map to "Next area". If ambiguous, ask: "Continue with more questions about [area], or move to the next area?" @@ -420,10 +695,18 @@ Ask 4 questions per area before offering to continue or move on. Each answer oft - Loop: discuss new areas, then prompt again - If "I'm ready for context": Proceed to write_context +**Canonical ref accumulation during discussion:** +When the user references a doc, spec, or ADR during any answer — e.g., "read adr-014", "check the MCP spec", "per browse-spec.md" — immediately: +1. read the referenced doc (or confirm it exists) +2. Add it to the canonical refs accumulator with full relative path +3. Use what you learned from the doc to inform subsequent questions + +These user-referenced docs are often MORE important than ROADMAP.md refs because they represent docs the user specifically wants downstream agents to follow. Never drop them. + **question design:** - Options should be concrete, not abstract ("Cards" not "Option A") -- Each answer should inform the next question -- If user picks "Other" to provide freeform input (e.g., "let me describe it", "something else", or an open-ended reply), ask your follow-up as plain text — NOT another question. Wait for them to type at the normal prompt, then reflect their input back and confirm before resuming question for the next question. +- Each answer should inform the next question or next batch +- If user picks "Other" to provide freeform input (e.g., "let me describe it", "something else", or an open-ended reply), ask your follow-up as plain text — NOT another question. Wait for them to type at the normal prompt, then reflect their input back and confirm before resuming question or the next numbered batch. **Scope creep handling:** If user mentions something outside the phase domain: @@ -435,11 +718,23 @@ Back to [current area]: [return to current question]" ``` Track deferred ideas internally. + +**Track discussion log data internally:** +For each question asked, accumulate: +- Area name +- All options presented (label + description) +- Which option the user selected (or their free-text response) +- Any follow-up notes or clarifications the user provided +This data is used to generate DISCUSSION-LOG.md in the `write_context` step. Create CONTEXT.md capturing decisions made. +**Also generate DISCUSSION-LOG.md** — a full audit trail of the discuss-phase Q&A. +This file is for human reference only (software audits, compliance reviews). It is NOT +consumed by downstream agents (researcher, planner, executor). + **Find or create phase directory:** Use values from init: `phase_dir`, `phase_slug`, `padded_phase`. @@ -470,17 +765,43 @@ mkdir -p ".planning/phases/${padded_phase}-${phase_slug}" ## Implementation Decisions ### [Category 1 that was discussed] -- [Decision or preference captured] -- [Another decision if applicable] +- **D-01:** [Decision or preference captured] +- **D-02:** [Another decision if applicable] ### [Category 2 that was discussed] -- [Decision or preference captured] +- **D-03:** [Decision or preference captured] ### OpenCode's Discretion [Areas where user said "you decide" — note that OpenCode has flexibility here] +### Folded Todos +[If any todos were folded into scope from the cross_reference_todos step, list them here. +Each entry should include the todo title, original problem, and how it fits this phase's scope. +If no todos were folded: omit this subsection entirely.] + + +## Canonical References + +**Downstream agents MUST read these before planning or implementing.** + +[MANDATORY section. write the FULL accumulated canonical refs list here. +Sources: ROADMAP.md refs + REQUIREMENTS.md refs + user-referenced docs during +discussion + any docs discovered during codebase scout. Group by topic area. +Every entry needs a full relative path — not just a name.] + +### [Topic area 1] +- `path/to/adr-or-spec.md` — [What it decides/defines that's relevant] +- `path/to/doc.md` §N — [Specific section reference] + +### [Topic area 2] +- `path/to/feature-doc.md` — [What this doc defines] + +[If no external specs: "No external specs — requirements fully captured in decisions above"] + + + ## Existing Code Insights @@ -509,6 +830,12 @@ mkdir -p ".planning/phases/${padded_phase}-${phase_slug}" [Ideas that came up but belong in other phases. Don't lose them.] +### Reviewed Todos (not folded) +[If any todos were reviewed in cross_reference_todos but not folded into scope, +list them here so future phases know they were considered. +Each entry: todo title + reason it was deferred (out of scope, belongs in Phase Y, etc.) +If no reviewed-but-deferred todos: omit this subsection entirely.] + [If none: "None — discussion stayed within phase scope"] @@ -546,14 +873,15 @@ Created: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md **Phase ${PHASE}: [Name]** — [Goal from ROADMAP.md] -`/gsd-plan-phase ${PHASE}` +`/gsd-plan-phase ${PHASE} ${GSD_WS}` *`/new` first → fresh context window* --- **Also available:** -- `/gsd-plan-phase ${PHASE} --skip-research` — plan without research +- `/gsd-plan-phase ${PHASE} --skip-research ${GSD_WS}` — plan without research +- `/gsd-ui-phase ${PHASE} ${GSD_WS}` — generate UI design contract before planning (if phase has frontend work) - Review/edit CONTEXT.md before continuing --- @@ -561,10 +889,54 @@ Created: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md -Commit phase context (uses `commit_docs` from init internally): +**write DISCUSSION-LOG.md before committing:** + +**File location:** `${phase_dir}/${padded_phase}-DISCUSSION-LOG.md` + +```markdown +# Phase [X]: [Name] - Discussion Log + +> **Audit trail only.** Do not use as input to planning, research, or execution agents. +> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered. + +**Date:** [ISO date] +**Phase:** [phase number]-[phase name] +**Areas discussed:** [comma-separated list] + +--- + +[For each gray area discussed:] + +## [Area Name] + +| Option | Description | Selected | +|--------|-------------|----------| +| [Option 1] | [Description from question] | | +| [Option 2] | [Description] | ✓ | +| [Option 3] | [Description] | | + +**User's choice:** [Selected option or free-text response] +**Notes:** [Any clarifications, follow-up context, or rationale the user provided] + +--- + +[Repeat for each area] + +## OpenCode's Discretion + +[List areas where user said "you decide" or deferred to OpenCode] + +## Deferred Ideas + +[Ideas mentioned during discussion that were noted for future phases] +``` + +write file. + +Commit phase context and discussion log: ```bash -node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs(${padded_phase}): capture phase context" --files "${phase_dir}/${padded_phase}-CONTEXT.md" +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs(${padded_phase}): capture phase context" --files "${phase_dir}/${padded_phase}-CONTEXT.md" "${phase_dir}/${padded_phase}-DISCUSSION-LOG.md" ``` Confirm: "Committed: docs(${padded_phase}): capture phase context" @@ -620,7 +992,7 @@ Context captured. Launching plan-phase... Launch plan-phase using the skill tool to avoid nested task sessions (which cause runtime freezes due to deep agent nesting — see #686): ``` -skill(skill="gsd-plan-phase", args="${PHASE} --auto") +skill(skill="gsd-plan-phase", args="${PHASE} --auto ${GSD_WS}") ``` This keeps the auto-advance chain flat — discuss, plan, and execute all run at the same nesting level rather than spawning increasingly deep task agents. @@ -634,23 +1006,23 @@ This keeps the auto-advance chain flat — discuss, plan, and execute all run at Auto-advance pipeline finished: discuss → plan → execute - Next: /gsd-discuss-phase ${NEXT_PHASE} --auto + Next: /gsd-discuss-phase ${NEXT_PHASE} --auto ${GSD_WS} */new first → fresh context window* ``` - **PLANNING COMPLETE** → Planning done, execution didn't complete: ``` Auto-advance partial: Planning complete, execution did not finish. - Continue: /gsd-execute-phase ${PHASE} + Continue: /gsd-execute-phase ${PHASE} ${GSD_WS} ``` - **PLANNING INCONCLUSIVE / CHECKPOINT** → Stop chain: ``` Auto-advance stopped: Planning needs input. - Continue: /gsd-plan-phase ${PHASE} + Continue: /gsd-plan-phase ${PHASE} ${GSD_WS} ``` - **GAPS FOUND** → Stop chain: ``` Auto-advance stopped: Gaps found during execution. - Continue: /gsd-plan-phase ${PHASE} --gaps + Continue: /gsd-plan-phase ${PHASE} --gaps ${GSD_WS} ``` **If neither `--auto` nor config enabled:** @@ -669,6 +1041,7 @@ Route to `confirm_creation` step (existing behavior — show manual next steps). - Each selected area explored until user satisfied (with code-informed and prior-decision-informed options) - Scope creep redirected to deferred ideas - CONTEXT.md captures actual decisions, not vague vision +- CONTEXT.md includes canonical_refs section with full file paths to every spec/ADR/doc downstream agents need (MANDATORY — never omit) - CONTEXT.md includes code_context section with reusable assets and patterns - Deferred ideas preserved for future phases - STATE.md updated with session info diff --git a/gsd-opencode/get-shit-done/workflows/do.md b/gsd-opencode/get-shit-done/workflows/do.md new file mode 100644 index 0000000..0755779 --- /dev/null +++ b/gsd-opencode/get-shit-done/workflows/do.md @@ -0,0 +1,104 @@ + +Analyze freeform text from the user and route to the most appropriate GSD command. This is a dispatcher — it never does the work itself. Match user intent to the best command, confirm the routing, and hand off. + + + +read all files referenced by the invoking prompt's execution_context before starting. + + + + + +**Check for input.** + +If `$ARGUMENTS` is empty, ask via question: + +``` +What would you like to do? Describe the task, bug, or idea and I'll route it to the right GSD command. +``` + +Wait for response before continuing. + + + +**Check if project exists.** + +```bash +INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" state load 2>/dev/null) +``` + +Track whether `.planning/` exists — some routes require it, others don't. + + + +**Match intent to command.** + +Evaluate `$ARGUMENTS` against these routing rules. Apply the **first matching** rule: + +| If the text describes... | Route to | Why | +|--------------------------|----------|-----| +| Starting a new project, "set up", "initialize" | `/gsd-new-project` | Needs full project initialization | +| Mapping or analyzing an existing codebase | `/gsd-map-codebase` | Codebase discovery | +| A bug, error, crash, failure, or something broken | `/gsd-debug` | Needs systematic investigation | +| Exploring, researching, comparing, or "how does X work" | `/gsd-research-phase` | Domain research before planning | +| Discussing vision, "how should X look", brainstorming | `/gsd-discuss-phase` | Needs context gathering | +| A complex task: refactoring, migration, multi-file architecture, system redesign | `/gsd-add-phase` | Needs a full phase with plan/build cycle | +| Planning a specific phase or "plan phase N" | `/gsd-plan-phase` | Direct planning request | +| Executing a phase or "build phase N", "run phase N" | `/gsd-execute-phase` | Direct execution request | +| Running all remaining phases automatically | `/gsd-autonomous` | Full autonomous execution | +| A review or quality concern about existing work | `/gsd-verify-work` | Needs verification | +| Checking progress, status, "where am I" | `/gsd-progress` | Status check | +| Resuming work, "pick up where I left off" | `/gsd-resume-work` | Session restoration | +| A note, idea, or "remember to..." | `/gsd-add-todo` | Capture for later | +| Adding tests, "write tests", "test coverage" | `/gsd-add-tests` | Test generation | +| Completing a milestone, shipping, releasing | `/gsd-complete-milestone` | Milestone lifecycle | +| A specific, actionable, small task (add feature, fix typo, update config) | `/gsd-quick` | Self-contained, single executor | + +**Requires `.planning/` directory:** All routes except `/gsd-new-project`, `/gsd-map-codebase`, `/gsd-help`, and `/gsd-join-discord`. If the project doesn't exist and the route requires it, suggest `/gsd-new-project` first. + +**Ambiguity handling:** If the text could reasonably match multiple routes, ask the user via question with the top 2-3 options. For example: + +``` +"Refactor the authentication system" could be: +1. /gsd-add-phase — Full planning cycle (recommended for multi-file refactors) +2. /gsd-quick — Quick execution (if scope is small and clear) + +Which approach fits better? +``` + + + +**Show the routing decision.** + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► ROUTING +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +**Input:** {first 80 chars of $ARGUMENTS} +**Routing to:** {chosen command} +**Reason:** {one-line explanation} +``` + + + +**Invoke the chosen command.** + +Run the selected `/gsd-*` command, passing `$ARGUMENTS` as args. + +If the chosen command expects a phase number and one wasn't provided in the text, extract it from context or ask via question. + +After invoking the command, stop. The dispatched command handles everything from here. + + + + + +- [ ] Input validated (not empty) +- [ ] Intent matched to exactly one GSD command +- [ ] Ambiguity resolved via user question (if needed) +- [ ] Project existence checked for routes that require it +- [ ] Routing decision displayed before dispatch +- [ ] Command invoked with appropriate arguments +- [ ] No work done directly — dispatcher only + diff --git a/gsd-opencode/get-shit-done/workflows/execute-phase.md b/gsd-opencode/get-shit-done/workflows/execute-phase.md index 1f04718..65b0352 100644 --- a/gsd-opencode/get-shit-done/workflows/execute-phase.md +++ b/gsd-opencode/get-shit-done/workflows/execute-phase.md @@ -1,23 +1,69 @@ - + Execute all plans in a phase using wave-based parallel execution. Orchestrator stays lean — delegates plan execution to subagents. - + Orchestrator coordinates, not executes. Each subagent loads the full execute-plan context. Orchestrator: discover plans → analyze deps → group waves → spawn agents → handle checkpoints → collect results. + +**Subagent spawning is runtime-specific:** +- **OpenCode:** Uses `task(subagent_type="gsd-executor", ...)` — blocks until complete, returns result +- **Copilot:** Subagent spawning does not reliably return completion signals. **Default to + sequential inline execution**: read and follow execute-plan.md directly for each plan + instead of spawning parallel agents. Only attempt parallel spawning if the user + explicitly requests it — and in that case, rely on the spot-check fallback in step 3 + to detect completion. +- **Other runtimes:** If `task`/`task` tool is unavailable, use sequential inline execution as the + fallback. Check for tool availability at runtime rather than assuming based on runtime name. + +**Fallback rule:** If a spawned agent completes its work (commits visible, SUMMARY.md exists) but +the orchestrator never receives the completion signal, treat it as successful based on spot-checks +and continue to the next wave/plan. Never block indefinitely waiting for a signal — always verify +via filesystem and git state. + + read STATE.md before any operation to load project context. + +These are the valid GSD subagent types registered in .OpenCode/agents/ (or equivalent for your runtime). +Always use the exact name from this list — do not fall back to 'general' or other built-in types: + +- gsd-executor — Executes plan tasks, commits, creates SUMMARY.md +- gsd-verifier — Verifies phase completion, checks quality gates +- gsd-planner — Creates detailed plans from phase scope +- gsd-phase-researcher — Researches technical approaches for a phase +- gsd-plan-checker — Reviews plan quality before execution +- gsd-debugger — Diagnoses and fixes issues +- gsd-codebase-mapper — Maps project structure and dependencies +- gsd-integration-checker — Checks cross-phase integration +- gsd-nyquist-auditor — Validates verification coverage +- gsd-ui-researcher — Researches UI/UX approaches +- gsd-ui-checker — Reviews UI implementation quality +- gsd-ui-auditor — Audits UI against design requirements + + + +Parse `$ARGUMENTS` before loading any context: + +- First positional token → `PHASE_ARG` +- Optional `--wave N` → `WAVE_FILTER` +- Optional `--gaps-only` keeps its current meaning + +If `--wave` is absent, preserve the current behavior of executing all incomplete waves in the phase. + + Load all context in one call: ```bash INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init execute-phase "${PHASE_ARG}") if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +AGENT_SKILLS=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-executor 2>/dev/null) ``` Parse JSON for: `executor_model`, `verifier_model`, `commit_docs`, `parallelization`, `branching_strategy`, `branch_name`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `plans`, `incomplete_plans`, `plan_count`, `incomplete_count`, `state_exists`, `roadmap_exists`, `phase_req_ids`. @@ -28,14 +74,71 @@ Parse JSON for: `executor_model`, `verifier_model`, `commit_docs`, `parallelizat When `parallelization` is false, plans within a wave execute sequentially. -**Sync chain flag with intent** — if user invoked manually (no `--auto`), clear the ephemeral chain flag from any previous interrupted `--auto` chain. This does NOT touch `workflow.auto_advance` (the user's persistent settings preference). Must happen before any config reads (checkpoint handling also reads auto-advance flags): +**Runtime detection for Copilot:** +Check if the current runtime is Copilot by testing for the `@gsd-executor` agent pattern +or absence of the `task()` subagent API. If running under Copilot, force sequential inline +execution regardless of the `parallelization` setting — Copilot's subagent completion +signals are unreliable (see ``). Set `COPILOT_SEQUENTIAL=true` +internally and skip the `execute_waves` step in favor of `check_interactive_mode`'s +inline path for each plan. + +**REQUIRED — Sync chain flag with intent.** If user invoked manually (no `--auto`), clear the ephemeral chain flag from any previous interrupted `--auto` chain. This prevents stale `_auto_chain_active: true` from causing unwanted auto-advance. This does NOT touch `workflow.auto_advance` (the user's persistent settings preference). You MUST execute this bash block before any config reads: ```bash +# REQUIRED: prevents stale auto-chain from previous --auto runs if [[ ! "$ARGUMENTS" =~ --auto ]]; then node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-set workflow._auto_chain_active false 2>/dev/null fi ``` + +**Parse `--interactive` flag from $ARGUMENTS.** + +**If `--interactive` flag present:** Switch to interactive execution mode. + +Interactive mode executes plans sequentially **inline** (no subagent spawning) with user +checkpoints between tasks. The user can review, modify, or redirect work at any point. + +**Interactive execution flow:** + +1. Load plan inventory as normal (discover_and_group_plans) +2. For each plan (sequentially, ignoring wave grouping): + + a. **Present the plan to the user:** + ``` + ## Plan {plan_id}: {plan_name} + + Objective: {from plan file} + Tasks: {task_count} + + Options: + - Execute (proceed with all tasks) + - Review first (show task breakdown before starting) + - Skip (move to next plan) + - Stop (end execution, save progress) + ``` + + b. **If "Review first":** read and display the full plan file. Ask again: Execute, Modify, Skip. + + c. **If "Execute":** read and follow `$HOME/.config/opencode/get-shit-done/workflows/execute-plan.md` **inline** + (do NOT spawn a subagent). Execute tasks one at a time. + + d. **After each task:** Pause briefly. If the user intervenes (types anything), stop and address + their feedback before continuing. Otherwise proceed to next task. + + e. **After plan complete:** Show results, commit, create SUMMARY.md, then present next plan. + +3. After all plans: proceed to verification (same as normal mode). + +**Benefits of interactive mode:** +- No subagent overhead — dramatically lower token usage +- User catches mistakes early — saves costly verification cycles +- Maintains GSD's planning/tracking structure +- Best for: small phases, bug fixes, verification gaps, learning GSD + +**Skip to handle_branching step** (interactive plans execute inline after grouping). + + Check `branching_strategy` from init: @@ -53,6 +156,12 @@ All subsequent commits go to this branch. User handles merging. From init JSON: `phase_dir`, `plan_count`, `incomplete_count`. Report: "Found {plan_count} plans in {phase_dir} ({incomplete_count} incomplete)" + +**Update STATE.md for phase start:** +```bash +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" state begin-phase --phase "${PHASE_NUMBER}" --name "${PHASE_NAME}" --plans "${PLAN_COUNT}" +``` +This updates Status, Last Activity, Current focus, Current Position, and plan counts in STATE.md so frontmatter and body text reflect the active phase immediately. @@ -64,13 +173,19 @@ PLAN_INDEX=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" phase Parse JSON for: `phase`, `plans[]` (each with `id`, `wave`, `autonomous`, `objective`, `files_modified`, `task_count`, `has_summary`), `waves` (map of wave number → plan IDs), `incomplete`, `has_checkpoints`. -**Filtering:** Skip plans where `has_summary: true`. If `--gaps-only`: also skip non-gap_closure plans. If all filtered: "No matching incomplete plans" → exit. +**Filtering:** Skip plans where `has_summary: true`. If `--gaps-only`: also skip non-gap_closure plans. If `WAVE_FILTER` is set: also skip plans whose `wave` does not equal `WAVE_FILTER`. + +**Wave safety check:** If `WAVE_FILTER` is set and there are still incomplete plans in any lower wave that match the current execution mode, STOP and tell the user to finish earlier waves first. Do not let Wave 2+ execute while prerequisite earlier-wave plans remain incomplete. + +If all filtered: "No matching incomplete plans" → exit. Report: ``` ## Execution Plan -**Phase {X}: {Name}** — {total_plans} plans across {wave_count} waves +**Phase {X}: {Name}** — {total_plans} matching plans across {wave_count} wave(s) + +{If WAVE_FILTER is set: `Wave filter active: executing only Wave {WAVE_FILTER}`.} | Wave | Plans | What it builds | |------|-------|----------------| @@ -80,7 +195,7 @@ Report: -Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`, sequential if `false`. +Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`, sequential if `false`. **For each wave:** @@ -104,19 +219,29 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true` 2. **Spawn executor agents:** - Pass paths only — executors read files themselves with their fresh 200k context. - This keeps orchestrator context lean (~10-15%). + Pass paths only — executors read files themselves with their fresh context window. + For 200k models, this keeps orchestrator context lean (~10-15%). + For 1M+ models (Opus 4.6, Sonnet 4.6), richer context can be passed directly. ``` task( subagent_type="gsd-executor", model="{executor_model}", + isolation="worktree", prompt=" Execute plan {plan_number} of phase {phase_number}-{phase_name}. Commit each task atomically. Create SUMMARY.md. Update STATE.md and ROADMAP.md. + + You are running as a PARALLEL executor agent. Use --no-verify on all git + commits to avoid pre-commit hook contention with other agents. The + orchestrator validates hooks once after all agents complete. + For gsd-tools commits: add --no-verify flag. + For direct git commits: use git commit --no-verify -m "..." + + @$HOME/.config/opencode/get-shit-done/workflows/execute-plan.md @$HOME/.config/opencode/get-shit-done/templates/summary.md @@ -127,12 +252,22 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true` read these files at execution start using the read tool: - {phase_dir}/{plan_file} (Plan) + - .planning/PROJECT.md (Project context — core value, requirements, evolution rules) - .planning/STATE.md (State) - .planning/config.json (Config, if exists) - ./AGENTS.md (Project instructions, if exists — follow project-specific guidelines and coding conventions) - .OpenCode/skills/ or .agents/skills/ (Project skills, if either exists — list skills, read SKILL.md for each, follow relevant rules during implementation) + ${AGENT_SKILLS} + + + If AGENTS.md or project instructions reference MCP tools (e.g. jCodeMunch, context7, + or other MCP servers), prefer those tools over grep/glob for code navigation when available. + MCP tools often save significant tokens by providing structured code indexes. + Check tool availability first — if MCP tools are not accessible, fall back to grep/glob. + + - [ ] All tasks executed - [ ] Each task committed individually @@ -146,7 +281,39 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true` 3. **Wait for all agents in wave to complete.** -4. **Report completion — spot-check claims first:** + **Completion signal fallback (Copilot and runtimes where task() may not return):** + + If a spawned agent does not return a completion signal but appears to have finished + its work, do NOT block indefinitely. Instead, verify completion via spot-checks: + + ```bash + # For each plan in this wave, check if the executor finished: + SUMMARY_EXISTS=$(test -f "{phase_dir}/{plan_number}-{plan_padded}-SUMMARY.md" && echo "true" || echo "false") + COMMITS_FOUND=$(git log --oneline --all --grep="{phase_number}-{plan_padded}" --since="1 hour ago" | head -1) + ``` + + **If SUMMARY.md exists AND commits are found:** The agent completed successfully — + treat as done and proceed to step 4. Log: `"✓ {Plan ID} completed (verified via spot-check — completion signal not received)"` + + **If SUMMARY.md does NOT exist after a reasonable wait:** The agent may still be + running or may have failed silently. Check `git log --oneline -5` for recent + activity. If commits are still appearing, wait longer. If no activity, report + the plan as failed and route to the failure handler in step 5. + + **This fallback applies automatically to all runtimes.** OpenCode's task() normally + returns synchronously, but the fallback ensures resilience if it doesn't. + +4. **Post-wave hook validation (parallel mode only):** + + When agents committed with `--no-verify`, run pre-commit hooks once after the wave: + ```bash + # Run project's pre-commit hooks on the current state + git diff --cached --quiet || git stash # stash any unstaged changes + git hook run pre-commit 2>&1 || echo "⚠ Pre-commit hooks failed — review before continuing" + ``` + If hooks fail: report the failure and ask "Fix hook issues now?" or "Continue to next wave?" + +5. **Report completion — spot-check claims first:** For each SUMMARY.md: - Verify first 2 files from `key-files.created` exist on disk @@ -177,6 +344,27 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true` For real failures: report which plan failed → ask "Continue?" or "Stop?" → if continue, dependent plans may also fail. If stop, partial completion report. +5b. **Pre-wave dependency check (waves 2+ only):** + + Before spawning wave N+1, for each plan in the upcoming wave: + ```bash + node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" verify key-links {phase_dir}/{plan}-PLAN.md + ``` + + If any key-link from a PRIOR wave's artifact fails verification: + + ## Cross-Plan Wiring Gap + + | Plan | Link | From | Expected Pattern | Status | + |------|------|------|-----------------|--------| + | {plan} | {via} | {from} | {pattern} | NOT FOUND | + + Wave {N} artifacts may not be properly wired. Options: + 1. Investigate and fix before continuing + 2. Continue (may cause cascading failures in wave {N+1}) + + Key-links referencing files in the CURRENT (upcoming) wave are skipped. + 6. **Execute checkpoint plans between waves** — see ``. 7. **Proceed to next wave.** @@ -250,6 +438,37 @@ After all waves: ``` + +If `WAVE_FILTER` was used, re-run plan discovery after execution: + +```bash +POST_PLAN_INDEX=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" phase-plan-index "${PHASE_NUMBER}") +``` + +Apply the same "incomplete" filtering rules as earlier: +- ignore plans with `has_summary: true` +- if `--gaps-only`, only consider `gap_closure: true` plans + +**If incomplete plans still remain anywhere in the phase:** +- STOP here +- Do NOT run phase verification +- Do NOT mark the phase complete in ROADMAP/STATE +- Present: + +```markdown +## Wave {WAVE_FILTER} Complete + +Selected wave finished successfully. This phase still has incomplete plans, so phase-level verification and completion were intentionally skipped. + +/gsd-execute-phase {phase} ${GSD_WS} # Continue remaining waves +/gsd-execute-phase {phase} --wave {next} ${GSD_WS} # Run the next wave explicitly +``` + +**If no incomplete plans remain after the selected wave finishes:** +- continue with the normal phase-level verification and completion flow below +- this means the selected wave happened to be the last remaining work in the phase + + **For decimal/polish phases only (X.Y pattern):** Close the feedback loop by resolving parent UAT and debug artifacts. @@ -300,9 +519,74 @@ node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs(phase ``` + +Run prior phases' test suites to catch cross-phase regressions BEFORE verification. + +**Skip if:** This is the first phase (no prior phases), or no prior VERIFICATION.md files exist. + +**Step 1: Discover prior phases' test files** +```bash +# Find all VERIFICATION.md files from prior phases in current milestone +PRIOR_VERIFICATIONS=$(find .planning/phases/ -name "*-VERIFICATION.md" ! -path "*${PHASE_NUMBER}*" 2>/dev/null) +``` + +**Step 2: Extract test file lists from prior verifications** + +For each VERIFICATION.md found, look for test file references: +- Lines containing `test`, `spec`, or `__tests__` paths +- The "Test Suite" or "Automated Checks" section +- File patterns from `key-files.created` in corresponding SUMMARY.md files that match `*.test.*` or `*.spec.*` + +Collect all unique test file paths into `REGRESSION_FILES`. + +**Step 3: Run regression tests (if any found)** + +```bash +# Detect test runner and run prior phase tests +if [ -f "package.json" ]; then + # Node.js — use project's test runner + npx jest ${REGRESSION_FILES} --passWithNoTests --no-coverage -q 2>&1 || npx vitest run ${REGRESSION_FILES} 2>&1 +elif [ -f "Cargo.toml" ]; then + cargo test 2>&1 +elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then + python -m pytest ${REGRESSION_FILES} -q --tb=short 2>&1 +fi +``` + +**Step 4: Report results** + +If all tests pass: +``` +✓ Regression gate: {N} prior-phase test files passed — no regressions detected +``` +→ Proceed to verify_phase_goal + +If any tests fail: +``` +## ⚠ Cross-Phase Regression Detected + +Phase {X} execution may have broken functionality from prior phases. + +| Test File | Phase | Status | Detail | +|-----------|-------|--------|--------| +| {file} | {origin_phase} | FAILED | {first_failure_line} | + +Options: +1. Fix regressions before verification (recommended) +2. Continue to verification anyway (regressions will compound) +3. Abort phase — roll back and re-plan +``` + +Use question to present the options. + + Verify phase achieved its GOAL, not just completed tasks. +```bash +VERIFIER_SKILLS=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-verifier 2>/dev/null) +``` + ``` task( prompt="Verify phase {phase_number} goal achievement. @@ -311,7 +595,8 @@ Phase goal: {goal from ROADMAP.md} Phase requirement IDs: {phase_req_ids} Check must_haves against actual codebase. Cross-reference requirement IDs from PLAN frontmatter against REQUIREMENTS.md — every ID MUST be accounted for. -Create VERIFICATION.md.", +Create VERIFICATION.md. +${VERIFIER_SKILLS}", subagent_type="gsd-verifier", model="{verifier_model}" ) @@ -326,9 +611,54 @@ grep "^status:" "$PHASE_DIR"/*-VERIFICATION.md | cut -d: -f2 | tr -d ' ' |--------|--------| | `passed` | → update_roadmap | | `human_needed` | Present items for human testing, get approval or feedback | -| `gaps_found` | Present gap summary, offer `/gsd-plan-phase {phase} --gaps` | +| `gaps_found` | Present gap summary, offer `/gsd-plan-phase {phase} --gaps ${GSD_WS}` | **If human_needed:** + +**Step A: Persist human verification items as UAT file.** + +Create `{phase_dir}/{phase_num}-HUMAN-UAT.md` using UAT template format: + +```markdown +--- +status: partial +phase: {phase_num}-{phase_name} +source: [{phase_num}-VERIFICATION.md] +started: [now ISO] +updated: [now ISO] +--- + +## Current Test + +[awaiting human testing] + +## Tests + +{For each human_verification item from VERIFICATION.md:} + +### {N}. {item description} +expected: {expected behavior from VERIFICATION.md} +result: [pending] + +## Summary + +total: {count} +passed: 0 +issues: 0 +pending: {count} +skipped: 0 +blocked: 0 + +## Gaps +``` + +Commit the file: +```bash +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "test({phase_num}): persist human verification items as UAT" --files "{phase_dir}/{phase_num}-HUMAN-UAT.md" +``` + +**Step B: Present to user:** + ``` ## ✓ Phase {X}: {Name} — Human Verification Required @@ -336,9 +666,15 @@ All automated checks passed. {N} items need human testing: {From VERIFICATION.md human_verification section} +Items saved to `{phase_num}-HUMAN-UAT.md` — they will appear in `/gsd-progress` and `/gsd-audit-uat`. + "approved" → continue | Report issues → gap closure ``` +**If user says "approved":** Proceed to `update_roadmap`. The HUMAN-UAT.md file persists with `status: partial` and will surface in future progress checks until the user runs `/gsd-verify-work` on it. + +**If user reports issues:** Proceed to gap closure as currently implemented. + **If gaps_found:** ``` ## ⚠ Phase {X}: {Name} — Gaps Found @@ -352,15 +688,15 @@ All automated checks passed. {N} items need human testing: --- ## ▶ Next Up -`/gsd-plan-phase {X} --gaps` +`/gsd-plan-phase {X} --gaps ${GSD_WS}` *`/new` first → fresh context window* Also: `cat {phase_dir}/{phase_num}-VERIFICATION.md` — full report -Also: `/gsd-verify-work {X}` — manual testing first +Also: `/gsd-verify-work {X} ${GSD_WS}` — manual testing first ``` -Gap closure cycle: `/gsd-plan-phase {X} --gaps` reads VERIFICATION.md → creates gap plans with `gap_closure: true` → user runs `/gsd-execute-phase {X} --gaps-only` → verifier re-runs. +Gap closure cycle: `/gsd-plan-phase {X} --gaps ${GSD_WS}` reads VERIFICATION.md → creates gap plans with `gap_closure: true` → user runs `/gsd-execute-phase {X} --gaps-only ${GSD_WS}` → verifier re-runs. @@ -376,14 +712,46 @@ The CLI handles: - Updating plan count to final - Advancing STATE.md to next phase - Updating REQUIREMENTS.md traceability +- Scanning for verification debt (returns `warnings` array) -Extract from result: `next_phase`, `next_phase_name`, `is_last_phase`. +Extract from result: `next_phase`, `next_phase_name`, `is_last_phase`, `warnings`, `has_warnings`. + +**If has_warnings is true:** +``` +## Phase {X} marked complete with {N} warnings: + +{list each warning} + +These items are tracked and will appear in `/gsd-progress` and `/gsd-audit-uat`. +``` ```bash node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs(phase-{X}): complete phase execution" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md {phase_dir}/*-VERIFICATION.md ``` + +**Evolve PROJECT.md to reflect phase completion (prevents planning document drift — #956):** + +PROJECT.md tracks validated requirements, decisions, and current state. Without this step, +PROJECT.md falls behind silently over multiple phases. + +1. read `.planning/PROJECT.md` +2. If the file exists and has a `## Validated Requirements` or `## Requirements` section: + - Move any requirements validated by this phase from Active → Validated + - Add a brief note: `Validated in Phase {X}: {Name}` +3. If the file has a `## Current State` or similar section: + - Update it to reflect this phase's completion (e.g., "Phase {X} complete — {one-liner}") +4. Update the `Last updated:` footer to today's date +5. Commit the change: + +```bash +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs(phase-{X}): evolve PROJECT.md after phase completion" --files .planning/PROJECT.md +``` + +**Skip this step if** `.planning/PROJECT.md` does not exist. + + **Exception:** If `gaps_found`, the `verify_phase_goal` step already presents the gap-closure path (`/gsd-plan-phase {X} --gaps`). No additional routing needed — skip auto-advance. @@ -433,15 +801,34 @@ Execute the transition workflow inline (do NOT use task — orchestrator context read and follow `$HOME/.config/opencode/get-shit-done/workflows/transition.md`, passing through the `--auto` flag so it propagates to the next phase invocation. -**If neither `--auto` nor `AUTO_CFG` is true:** +**If none of `--auto`, `AUTO_CHAIN`, or `AUTO_CFG` is true:** + +**STOP. Do not auto-advance. Do not execute transition. Do not plan next phase. Present options to the user and wait.** + +**IMPORTANT: There is NO `/gsd-transition` command. Never suggest it. The transition workflow is internal only.** + +``` +## ✓ Phase {X}: {Name} Complete + +/gsd-progress ${GSD_WS} — see updated roadmap +/gsd-discuss-phase {next} ${GSD_WS} — discuss next phase before planning +/gsd-plan-phase {next} ${GSD_WS} — plan next phase +/gsd-execute-phase {next} ${GSD_WS} — execute next phase +``` -The workflow ends. The user runs `/gsd-progress` or invokes the transition workflow manually. +Only suggest the commands listed above. Do not invent or hallucinate command names. -Orchestrator: ~10-15% context. Subagents: fresh 200k each. No polling (task blocks). No context bleed. +Orchestrator: ~10-15% context for 200k windows, can use more for 1M+ windows. +Subagents: fresh context each (200k-1M depending on model). No polling (task blocks). No context bleed. + +For 1M+ context models, consider: +- Passing richer context (code snippets, dependency outputs) directly to executors instead of just file paths +- Running small phases (≤3 plans, no dependencies) inline without subagent spawning overhead +- Relaxing /new recommendations — context rot onset is much further out with 5x window diff --git a/gsd-opencode/get-shit-done/workflows/execute-plan.md b/gsd-opencode/get-shit-done/workflows/execute-plan.md index 59c07fe..3eb89ef 100644 --- a/gsd-opencode/get-shit-done/workflows/execute-plan.md +++ b/gsd-opencode/get-shit-done/workflows/execute-plan.md @@ -1,6 +1,6 @@ - + Execute a phase prompt (PLAN.md) and create the outcome summary (SUMMARY.md). - + read STATE.md before any operation to load project context. @@ -9,6 +9,11 @@ read config.json for planning behavior settings. @$HOME/.config/opencode/get-shit-done/references/git-integration.md + +Valid GSD subagent types (use exact names — do not fall back to 'general'): +- gsd-executor — Executes plan tasks, commits, creates SUMMARY.md + + @@ -19,7 +24,7 @@ INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init execut if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi ``` -Extract from init JSON: `executor_model`, `commit_docs`, `phase_dir`, `phase_number`, `plans`, `summaries`, `incomplete_plans`, `state_path`, `config_path`. +Extract from init JSON: `executor_model`, `commit_docs`, `sub_repos`, `phase_dir`, `phase_number`, `plans`, `summaries`, `incomplete_plans`, `state_path`, `config_path`. If `.planning/` missing: error. @@ -27,8 +32,8 @@ If `.planning/` missing: error. ```bash # Use plans/summaries from INIT JSON, or list files -ls .planning/phases/XX-name/*-PLAN.md 2>/dev/null | sort -ls .planning/phases/XX-name/*-SUMMARY.md 2>/dev/null | sort +(ls .planning/phases/XX-name/*-PLAN.md 2>/dev/null || true) | sort +(ls .planning/phases/XX-name/*-SUMMARY.md 2>/dev/null || true) | sort ``` Find first PLAN without matching SUMMARY. Decimal phases supported (`01.1-hotfix/`): @@ -67,7 +72,7 @@ grep -n "type=\"checkpoint" .planning/phases/XX-name/{phase}-{plan}-PLAN.md | Verify-only | B (segmented) | Segments between checkpoints. After none/human-verify → SUBAGENT. After decision/human-action → MAIN | | Decision | C (main) | Execute entirely in main context | -**Pattern A:** init_agent_tracking → spawn task(subagent_type="gsd-executor", model=executor_model) with prompt: execute plan at [path], autonomous, all tasks + SUMMARY + commit, follow deviation/auth rules, report: plan name, tasks, SUMMARY path, commit hash → track agent_id → wait → update tracking → report. +**Pattern A:** init_agent_tracking → spawn task(subagent_type="gsd-executor", model=executor_model, isolation="worktree") with prompt: execute plan at [path], autonomous, all tasks + SUMMARY + commit, follow deviation/auth rules, report: plan name, tasks, SUMMARY path, commit hash → track agent_id → wait → update tracking → report. **Pattern B:** Execute segment-by-segment. Autonomous segments: spawn subagent for assigned tasks only (no SUMMARY/commit). Checkpoints: main context. After all segments: aggregate, create SUMMARY, commit. See segment_execution. @@ -135,9 +140,12 @@ If previous SUMMARY has unresolved "Issues Encountered" or "Next Phase Readiness Deviations are normal — handle via rules below. 1. read @context files from prompt -2. Per task: +2. **MCP tools:** If AGENTS.md or project instructions reference MCP tools (e.g. jCodeMunch for code navigation), prefer them over grep/glob when available. Fall back to grep/glob if MCP tools are not accessible. +3. Per task: + - **MANDATORY read_first gate:** If the task has a `` field, you MUST read every listed file BEFORE making any edits. This is not optional. Do not skip files because you "already know" what's in them — read them. The read_first files establish ground truth for the task. - `type="auto"`: if `tdd="true"` → TDD execution. Implement with deviation rules + auth gates. Verify done criteria. Commit (see task_commit). Track hash for Summary. - `type="checkpoint:*"`: STOP → checkpoint_protocol → wait for user → continue only after confirmation. + - **MANDATORY acceptance_criteria check:** After completing each task, if it has ``, verify EVERY criterion before moving to the next task. Use grep, file reads, or CLI commands to confirm each criterion. If any criterion fails, fix the implementation before proceeding. Do not skip criteria or mark them as "will verify later". 3. Run `` checks 4. Confirm `` met 5. Document deviations in Summary @@ -226,6 +234,25 @@ Errors: RED doesn't fail → investigate test/existing feature. GREEN doesn't pa See `$HOME/.config/opencode/get-shit-done/references/tdd.md` for structure. + +## Pre-commit Hook Failure Handling + +Your commits may trigger pre-commit hooks. Auto-fix hooks handle themselves transparently — files get fixed and re-staged automatically. + +**If running as a parallel executor agent (spawned by execute-phase):** +Use `--no-verify` on all commits. Pre-commit hooks cause build lock contention when multiple agents commit simultaneously (e.g., cargo lock fights in Rust projects). The orchestrator validates once after all agents complete. + +**If running as the sole executor (sequential mode):** +If a commit is BLOCKED by a hook: + +1. The `git commit` command fails with hook error output +2. read the error — it tells you exactly which hook and what failed +3. Fix the issue (type error, lint violation, secret leak, etc.) +4. `git add` the fixed files +5. Retry the commit +6. Budget 1-2 retry cycles per commit + + ## task Commit Protocol @@ -254,12 +281,35 @@ git add src/types/user.ts **4. Format:** `{type}({phase}-{plan}): {description}` with bullet points for key changes. + +**Sub-repos mode:** If `sub_repos` is configured (non-empty array from init context), use `commit-to-subrepo` instead of standard git commit. This routes files to their correct sub-repo based on path prefix. + +```bash +node $HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs commit-to-subrepo "{type}({phase}-{plan}): {description}" --files file1 file2 ... +``` + +The command groups files by sub-repo prefix and commits atomically to each. Returns JSON: `{ committed: true, repos: { "backend": { hash: "abc", files: [...] }, ... } }`. + +Record hashes from each repo in the response for SUMMARY tracking. + +**If `sub_repos` is empty or not set:** Use standard git commit flow below. + + **5. Record hash:** ```bash TASK_COMMIT=$(git rev-parse --short HEAD) TASK_COMMITS+=("task ${TASK_NUM}: ${TASK_COMMIT}") ``` +**6. Check for untracked generated files:** +```bash +git status --short | grep '^??' +``` +If new untracked files appeared after running scripts or tools, decide for each: +- **Commit it** — if it's a source file, config, or intentional artifact +- **Add to .gitignore** — if it's a generated/runtime output (build artifacts, `.env` files, cache files, compiled output) +- Do NOT leave generated files untracked + @@ -287,7 +337,22 @@ Orchestrator parses → presents to user → spawns fresh continuation with your -If verification fails: STOP. Present: "Verification failed for task [X]: [name]. Expected: [criteria]. Actual: [result]." Options: Retry | Skip (mark incomplete) | Stop (investigate). If skipped → SUMMARY "Issues Encountered". +If verification fails: + +**Check if node repair is enabled** (default: on): +```bash +NODE_REPAIR=$(node "./.OpenCode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.node_repair 2>/dev/null || echo "true") +``` + +If `NODE_REPAIR` is `true`: invoke `@./.OpenCode/get-shit-done/workflows/node-repair.md` with: +- FAILED_TASK: task number, name, done-criteria +- ERROR: expected vs actual result +- PLAN_CONTEXT: adjacent task names + phase goal +- REPAIR_BUDGET: `workflow.node_repair_budget` from config (default: 2) + +Node repair will attempt RETRY, DECOMPOSE, or PRUNE autonomously. Only reaches this gate again if repair budget is exhausted (ESCALATE). + +If `NODE_REPAIR` is `false` OR repair returns ESCALATE: STOP. Present: "Verification failed for task [X]: [name]. Expected: [criteria]. Actual: [result]. Repair attempted: [summary of what was tried]." Options: Retry | Skip (mark incomplete) | Stop (investigate). If skipped → SUMMARY "Issues Encountered". @@ -327,7 +392,7 @@ One-liner SUBSTANTIVE: "JWT auth with refresh rotation using jose library" not " Include: duration, start/end times, task count, file count. -Next: more plans → "Ready for {next-plan}" | last → "Phase complete, ready for transition". +Next: more plans → "Ready for {next-plan}" | last → "Phase complete, ready for next step". @@ -407,7 +472,7 @@ If .planning/codebase/ doesn't exist: skip. ```bash FIRST_TASK=$(git log --oneline --grep="feat({phase}-{plan}):" --grep="fix({phase}-{plan}):" --grep="test({phase}-{plan}):" --reverse | head -1 | cut -d' ' -f1) -git diff --name-only ${FIRST_TASK}^..HEAD 2>/dev/null +git diff --name-only ${FIRST_TASK}^..HEAD 2>/dev/null || true ``` Update only structural changes: new src/ dir → STRUCTURE.md | deps → STACK.md | file pattern → CONVENTIONS.md | API client → INTEGRATIONS.md | config → STACK.md | renamed → update paths. Skip code-only/bugfix/content changes. @@ -421,8 +486,8 @@ node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "" --files If `USER_SETUP_CREATED=true`: display `⚠️ USER SETUP REQUIRED` with path + env/config tasks at TOP. ```bash -ls -1 .planning/phases/[current-phase-dir]/*-PLAN.md 2>/dev/null | wc -l -ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null | wc -l +(ls -1 .planning/phases/[current-phase-dir]/*-PLAN.md 2>/dev/null || true) | wc -l +(ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null || true) | wc -l ``` | Condition | Route | Action | diff --git a/gsd-opencode/get-shit-done/workflows/fast.md b/gsd-opencode/get-shit-done/workflows/fast.md new file mode 100644 index 0000000..2b9fad9 --- /dev/null +++ b/gsd-opencode/get-shit-done/workflows/fast.md @@ -0,0 +1,105 @@ + +Execute a trivial task inline without subagent overhead. No PLAN.md, no task spawning, +no research, no plan checking. Just: understand → do → commit → log. + +For tasks like: fix a typo, update a config value, add a missing import, rename a +variable, commit uncommitted work, add a .gitignore entry, bump a version number. + +Use /gsd-quick for anything that needs multi-step planning or research. + + + + + +Parse `$ARGUMENTS` for the task description. + +If empty, ask: +``` +What's the quick fix? (one sentence) +``` + +Store as `$TASK`. + + + +**Before doing anything, verify this is actually trivial.** + +A task is trivial if it can be completed in: +- ≤ 3 file edits +- ≤ 1 minute of work +- No new dependencies or architecture changes +- No research needed + +If the task seems non-trivial (multi-file refactor, new feature, needs research), +say: + +``` +This looks like it needs planning. Use /gsd-quick instead: + /gsd-quick "{task description}" +``` + +And stop. + + + +Do the work directly: + +1. read the relevant file(s) +2. Make the change(s) +3. Verify the change works (run existing tests if applicable, or do a quick sanity check) + +**No PLAN.md.** Just do it. + + + +Commit the change atomically: + +```bash +git add -A +git commit -m "fix: {concise description of what changed}" +``` + +Use conventional commit format: `fix:`, `feat:`, `docs:`, `chore:`, `refactor:` as appropriate. + + + +If `.planning/STATE.md` exists, append to the "Quick Tasks Completed" table. +If the table doesn't exist, skip this step silently. + +```bash +# Check if STATE.md has quick tasks table +if grep -q "Quick Tasks Completed" .planning/STATE.md 2>/dev/null; then + # Append entry — workflow handles the format + echo "| $(date +%Y-%m-%d) | fast | $TASK | ✅ |" >> .planning/STATE.md +fi +``` + + + +Report completion: + +``` +✅ Done: {what was changed} + Commit: {short hash} + Files: {list of changed files} +``` + +No next-step suggestions. No workflow routing. Just done. + + + + + +- NEVER spawn a task/subagent — this runs inline +- NEVER create PLAN.md or SUMMARY.md files +- NEVER run research or plan-checking +- If the task takes more than 3 file edits, STOP and redirect to /gsd-quick +- If you're unsure how to implement it, STOP and redirect to /gsd-quick + + + +- [ ] task completed in current context (no subagents) +- [ ] Atomic git commit with conventional message +- [ ] STATE.md updated if it exists +- [ ] Total operation under 2 minutes wall time + diff --git a/gsd-opencode/get-shit-done/workflows/forensics.md b/gsd-opencode/get-shit-done/workflows/forensics.md new file mode 100644 index 0000000..7d350c1 --- /dev/null +++ b/gsd-opencode/get-shit-done/workflows/forensics.md @@ -0,0 +1,265 @@ +# Forensics Workflow + +Post-mortem investigation for failed or stuck GSD workflows. Analyzes git history, +`.planning/` artifacts, and file system state to detect anomalies and generate a +structured diagnostic report. + +**Principle:** This is a read-only investigation. Do not modify project files. +Only write the forensic report. + +--- + +## Step 1: Get Problem Description + +```bash +PROBLEM="$ARGUMENTS" +``` + +If `$ARGUMENTS` is empty, ask the user: +> "What went wrong? Describe the issue — e.g., 'autonomous mode got stuck on phase 3', +> 'execute-phase failed silently', 'costs seem unusually high'." + +Record the problem description for the report. + +## Step 2: Gather Evidence + +Collect data from all available sources. Missing sources are fine — adapt to what exists. + +### 2a. Git History + +```bash +# Recent commits (last 30) +git log --oneline -30 + +# Commits with timestamps for gap analysis +git log --format="%H %ai %s" -30 + +# Files changed in recent commits (detect repeated edits) +git log --name-only --format="" -20 | sort | uniq -c | sort -rn | head -20 + +# Uncommitted work +git status --short +git diff --stat +``` + +Record: +- Commit timeline (dates, messages, frequency) +- Most-edited files (potential stuck-loop indicator) +- Uncommitted changes (potential crash/interruption indicator) + +### 2b. Planning State + +read these files if they exist: +- `.planning/STATE.md` — current milestone, phase, progress, blockers, last session +- `.planning/ROADMAP.md` — phase list with status +- `.planning/config.json` — workflow configuration + +Extract: +- Current phase and its status +- Last recorded session stop point +- Any blockers or flags + +### 2c. Phase Artifacts + +For each phase directory in `.planning/phases/*/`: + +```bash +ls .planning/phases/*/ +``` + +For each phase, check which artifacts exist: +- `{padded}-PLAN.md` or `{padded}-PLAN-*.md` (execution plans) +- `{padded}-SUMMARY.md` (completion summary) +- `{padded}-VERIFICATION.md` (quality verification) +- `{padded}-CONTEXT.md` (design decisions) +- `{padded}-RESEARCH.md` (pre-planning research) + +Track: which phases have complete artifact sets vs gaps. + +### 2d. Session Reports + +read `.planning/reports/SESSION_REPORT.md` if it exists — extract last session outcomes, +work completed, token estimates. + +### 2e. Git Worktree State + +```bash +git worktree list +``` + +Check for orphaned worktrees (from crashed agents). + +## Step 3: Detect Anomalies + +Evaluate the gathered evidence against these anomaly patterns: + +### Stuck Loop Detection + +**Signal:** Same file appears in 3+ consecutive commits within a short time window. + +```bash +# Look for files committed repeatedly in sequence +git log --name-only --format="---COMMIT---" -20 +``` + +Parse commit boundaries. If any file appears in 3+ consecutive commits, flag as: +- **Confidence HIGH** if the commit messages are similar (e.g., "fix:", "fix:", "fix:" on same file) +- **Confidence MEDIUM** if the file appears frequently but commit messages vary + +### Missing Artifact Detection + +**Signal:** Phase appears complete (has commits, is past in roadmap) but lacks expected artifacts. + +For each phase that should be complete: +- PLAN.md missing → planning step was skipped +- SUMMARY.md missing → phase was not properly closed +- VERIFICATION.md missing → quality check was skipped + +### Abandoned Work Detection + +**Signal:** Large gap between last commit and current time, with STATE.md showing mid-execution. + +```bash +# Time since last commit +git log -1 --format="%ai" +``` + +If STATE.md shows an active phase but the last commit is >2 hours old and there are +uncommitted changes, flag as potential abandonment or crash. + +### Crash/Interruption Detection + +**Signal:** Uncommitted changes + STATE.md shows mid-execution + orphaned worktrees. + +Combine: +- `git status` shows modified/staged files +- STATE.md has an active execution entry +- `git worktree list` shows worktrees beyond the main one + +### Scope Drift Detection + +**Signal:** Recent commits touch files outside the current phase's expected scope. + +read the current phase PLAN.md to determine expected file paths. Compare against +files actually modified in recent commits. Flag any files that are clearly outside +the phase's domain. + +### Test Regression Detection + +**Signal:** Commit messages containing "fix test", "revert", or re-commits of test files. + +```bash +git log --oneline -20 | grep -iE "fix test|revert|broken|regression|fail" +``` + +## Step 4: Generate Report + +Create the forensics directory if needed: +```bash +mkdir -p .planning/forensics +``` + +write to `.planning/forensics/report-$(date +%Y%m%d-%H%M%S).md`: + +```markdown +# Forensic Report + +**Generated:** {ISO timestamp} +**Problem:** {user's description} + +--- + +## Evidence Summary + +### Git Activity +- **Last commit:** {date} — "{message}" +- **Commits (last 30):** {count} +- **Time span:** {earliest} → {latest} +- **Uncommitted changes:** {yes/no — list if yes} +- **Active worktrees:** {count — list if >1} + +### Planning State +- **Current milestone:** {version or "none"} +- **Current phase:** {number — name — status} +- **Last session:** {stopped_at from STATE.md} +- **Blockers:** {any flags from STATE.md} + +### Artifact Completeness +| Phase | PLAN | CONTEXT | RESEARCH | SUMMARY | VERIFICATION | +|-------|------|---------|----------|---------|-------------| +{for each phase: name | ✅/❌ per artifact} + +## Anomalies Detected + +### {Anomaly Type} — {Confidence: HIGH/MEDIUM/LOW} +**Evidence:** {specific commits, files, or state data} +**Interpretation:** {what this likely means} + +{repeat for each anomaly found} + +## Root Cause Hypothesis + +Based on the evidence above, the most likely explanation is: + +{1-3 sentence hypothesis grounded in the anomalies} + +## Recommended Actions + +1. {Specific, actionable remediation step} +2. {Another step if applicable} +3. {Recovery command if applicable — e.g., `/gsd-resume-work`, `/gsd-execute-phase N`} + +--- + +*Report generated by `/gsd-forensics`. All paths redacted for portability.* +``` + +**Redaction rules:** +- Replace absolute paths with relative paths (strip `$HOME` prefix) +- Remove any API keys, tokens, or credentials found in git diff output +- Truncate large diffs to first 50 lines + +## Step 5: Present Report + +Display the full forensic report inline. + +## Step 6: Offer Interactive Investigation + +> "Report saved to `.planning/forensics/report-{timestamp}.md`. +> +> I can dig deeper into any finding. Want me to: +> - Trace a specific anomaly to its root cause? +> - read specific files referenced in the evidence? +> - Check if a similar issue has been reported before?" + +If the user asks follow-up questions, answer from the evidence already gathered. +read additional files only if specifically needed. + +## Step 7: Offer Issue Creation + +If actionable anomalies were found (HIGH or MEDIUM confidence): + +> "Want me to create a GitHub issue for this? I'll format the findings and redact paths." + +If confirmed: +```bash +# Check if "bug" label exists before using it +BUG_LABEL=$(gh label list --search "bug" --json name -q '.[0].name' 2>/dev/null) +LABEL_FLAG="" +if [ -n "$BUG_LABEL" ]; then + LABEL_FLAG="--label bug" +fi + +gh issue create \ + --title "bug: {concise description from anomaly}" \ + $LABEL_FLAG \ + --body "{formatted findings from report}" +``` + +## Step 8: Update STATE.md + +```bash +gsd-tools.cjs state record-session \ + --stopped-at "Forensic investigation complete" \ + --resume-file ".planning/forensics/report-{timestamp}.md" +``` diff --git a/gsd-opencode/get-shit-done/workflows/health.md b/gsd-opencode/get-shit-done/workflows/health.md index 5ad335e..a50578a 100644 --- a/gsd-opencode/get-shit-done/workflows/health.md +++ b/gsd-opencode/get-shit-done/workflows/health.md @@ -1,6 +1,6 @@ - + Validate `.planning/` directory integrity and report actionable issues. Checks for missing files, invalid configurations, inconsistent state, and orphaned plans. Optionally repairs auto-fixable issues. - + read all files referenced by the invoking prompt's execution_context before starting. @@ -72,8 +72,8 @@ Errors: N | Warnings: N | Info: N ``` ## Warnings -- [W001] STATE.md references phase 5, but only phases 1-3 exist - Fix: Run /gsd-health --repair to regenerate +- [W002] STATE.md references phase 5, but only phases 1-3 exist + Fix: Review STATE.md manually before changing it; repair will not overwrite an existing STATE.md - [W005] Phase directory "1-setup" doesn't follow NN-name format Fix: Rename to match pattern (e.g., 01-setup) @@ -130,7 +130,7 @@ Report final status. | E004 | error | STATE.md not found | Yes | | E005 | error | config.json parse error | Yes | | W001 | warning | PROJECT.md missing required section | No | -| W002 | warning | STATE.md references invalid phase | Yes | +| W002 | warning | STATE.md references invalid phase | No | | W003 | warning | config.json not found | Yes | | W004 | warning | config.json invalid field value | No | | W005 | warning | Phase directory naming mismatch | No | @@ -148,7 +148,7 @@ Report final status. |--------|--------|------| | createConfig | Create config.json with defaults | None | | resetConfig | Delete + recreate config.json | Loses custom settings | -| regenerateState | Create STATE.md from ROADMAP structure | Loses session history | +| regenerateState | Create STATE.md from ROADMAP structure when it is missing | Loses session history | | addNyquistKey | Add workflow.nyquist_validation: true to config.json | None — matches existing default | **Not repairable (too risky):** @@ -157,3 +157,25 @@ Report final status. - Orphaned plan cleanup + + +**Windows-specific:** Check for stale OpenCode task directories that accumulate on crash/freeze. +These are left behind when subagents are force-killed and consume disk space. + +When `--repair` is active, detect and clean up: + +```bash +# Check for stale task directories (older than 24 hours) +TASKS_DIR="$HOME/.OpenCode/tasks" +if [ -d "$TASKS_DIR" ]; then + STALE_COUNT=$( (find "$TASKS_DIR" -maxdepth 1 -type d -mtime +1 2>/dev/null || true) | wc -l ) + if [ "$STALE_COUNT" -gt 0 ]; then + echo "⚠️ Found $STALE_COUNT stale task directories in $HOME/.config/opencode/tasks/" + echo " These are leftover from crashed subagent sessions." + echo " Run: rm -rf $HOME/.config/opencode/tasks/* (safe — only affects dead sessions)" + fi +fi +``` + +Report as info diagnostic: `I002 | info | Stale subagent task directories found | Yes (--repair removes them)` + diff --git a/gsd-opencode/get-shit-done/workflows/help.md b/gsd-opencode/get-shit-done/workflows/help.md index c082823..fbd1d67 100644 --- a/gsd-opencode/get-shit-done/workflows/help.md +++ b/gsd-opencode/get-shit-done/workflows/help.md @@ -1,6 +1,6 @@ - + Display the complete GSD command reference. Output ONLY the reference content. Do NOT add project-specific analysis, git status, next-step suggestions, or any commentary beyond the reference. - + # GSD Command Reference @@ -66,8 +66,11 @@ Help articulate your vision for a phase before planning. - Captures how you imagine this phase working - Creates CONTEXT.md with your vision, essentials, and boundaries - Use when you have ideas about how something should look/feel +- Optional `--batch` asks 2-5 related questions at a time instead of one-by-one Usage: `/gsd-discuss-phase 2` +Usage: `/gsd-discuss-phase 2 --batch` +Usage: `/gsd-discuss-phase 2 --batch=3` **`/gsd-research-phase `** Comprehensive ecosystem research for niche/complex domains. @@ -104,30 +107,67 @@ Result: Creates `.planning/phases/01-foundation/01-01-PLAN.md` ### Execution **`/gsd-execute-phase `** -Execute all plans in a phase. +Execute all plans in a phase, or run a specific wave. - Groups plans by wave (from frontmatter), executes waves sequentially - Plans within each wave run in parallel via task tool +- Optional `--wave N` flag executes only Wave `N` and stops unless the phase is now fully complete - Verifies phase goal after all plans complete - Updates REQUIREMENTS.md, ROADMAP.md, STATE.md Usage: `/gsd-execute-phase 5` +Usage: `/gsd-execute-phase 5 --wave 2` + +### Smart Router + +**`/gsd-do `** +Route freeform text to the right GSD command automatically. + +- Analyzes natural language input to find the best matching GSD command +- Acts as a dispatcher — never does the work itself +- Resolves ambiguity by asking you to pick between top matches +- Use when you know what you want but don't know which `/gsd-*` command to run + +Usage: `/gsd-do fix the login button` +Usage: `/gsd-do refactor the auth system` +Usage: `/gsd-do I want to start a new milestone` ### Quick Mode -**`/gsd-quick`** +**`/gsd-quick [--full] [--discuss] [--research]`** Execute small, ad-hoc tasks with GSD guarantees but skip optional agents. Quick mode uses the same system with a shorter path: -- Spawns planner + executor (skips researcher, checker, verifier) +- Spawns planner + executor (skips researcher, checker, verifier by default) - Quick tasks live in `.planning/quick/` separate from planned phases - Updates STATE.md tracking (not ROADMAP.md) -Use when you know exactly what to do and the task is small enough to not need research or verification. +Flags enable additional quality steps: +- `--discuss` — Lightweight discussion to surface gray areas before planning +- `--research` — Focused research agent investigates approaches before planning +- `--full` — Adds plan-checking (max 2 iterations) and post-execution verification + +Flags are composable: `--discuss --research --full` gives the complete quality pipeline for a single task. Usage: `/gsd-quick` +Usage: `/gsd-quick --research --full` Result: Creates `.planning/quick/NNN-slug/PLAN.md`, `.planning/quick/NNN-slug/SUMMARY.md` +--- + +**`/gsd-fast [description]`** +Execute a trivial task inline — no subagents, no planning files, no overhead. + +For tasks too small to justify planning: typo fixes, config changes, forgotten commits, simple additions. Runs in the current context, makes the change, commits, and logs to STATE.md. + +- No PLAN.md or SUMMARY.md created +- No subagent spawned (runs inline) +- ≤ 3 file edits — redirects to `/gsd-quick` if task is non-trivial +- Atomic commit with conventional message + +Usage: `/gsd-fast "fix the typo in README"` +Usage: `/gsd-fast "add .env to gitignore"` + ### Roadmap Management **`/gsd-add-phase `** @@ -169,10 +209,12 @@ Start a new milestone through unified flow. - Optional domain research (spawns 4 parallel researcher agents) - Requirements definition with scoping - Roadmap creation with phase breakdown +- Optional `--reset-phase-numbers` flag restarts numbering at Phase 1 and archives old phase dirs first for safety Mirrors `/gsd-new-project` flow for brownfield projects (existing PROJECT.md). Usage: `/gsd-new-milestone "v2.0 Features"` +Usage: `/gsd-new-milestone --reset-phase-numbers "v2.0 Features"` **`/gsd-complete-milestone `** Archive completed milestone and prepare for next version. @@ -232,6 +274,21 @@ Systematic debugging with persistent state across context resets. Usage: `/gsd-debug "login button doesn't work"` Usage: `/gsd-debug` (resume active session) +### Quick Notes + +**`/gsd-note `** +Zero-friction idea capture — one command, instant save, no questions. + +- Saves timestamped note to `.planning/notes/` (or `$HOME/.config/opencode/notes/` globally) +- Three subcommands: append (default), list, promote +- Promote converts a note into a structured todo +- Works without a project (falls back to global scope) + +Usage: `/gsd-note refactor the hook system` +Usage: `/gsd-note list` +Usage: `/gsd-note promote 3` +Usage: `/gsd-note --global cross-project idea` + ### Todo Management **`/gsd-add-todo [description]`** @@ -270,6 +327,65 @@ Validate built features through conversational UAT. Usage: `/gsd-verify-work 3` +### Ship Work + +**`/gsd-ship [phase]`** +Create a PR from completed phase work with an auto-generated body. + +- Pushes branch to remote +- Creates PR with summary from SUMMARY.md, VERIFICATION.md, REQUIREMENTS.md +- Optionally requests code review +- Updates STATE.md with shipping status + +Prerequisites: Phase verified, `gh` CLI installed and authenticated. + +Usage: `/gsd-ship 4` or `/gsd-ship 4 --draft` + +--- + +**`/gsd-review --phase N [--gemini] [--OpenCode] [--codex] [--all]`** +Cross-AI peer review — invoke external AI CLIs to independently review phase plans. + +- Detects available CLIs (gemini, OpenCode, codex) +- Each CLI reviews plans independently with the same structured prompt +- Produces REVIEWS.md with per-reviewer feedback and consensus summary +- Feed reviews back into planning: `/gsd-plan-phase N --reviews` + +Usage: `/gsd-review --phase 3 --all` + +--- + +**`/gsd-pr-branch [target]`** +Create a clean branch for pull requests by filtering out .planning/ commits. + +- Classifies commits: code-only (include), planning-only (exclude), mixed (include sans .planning/) +- Cherry-picks code commits onto a clean branch +- Reviewers see only code changes, no GSD artifacts + +Usage: `/gsd-pr-branch` or `/gsd-pr-branch main` + +--- + +**`/gsd-plant-seed [idea]`** +Capture a forward-looking idea with trigger conditions for automatic surfacing. + +- Seeds preserve WHY, WHEN to surface, and breadcrumbs to related code +- Auto-surfaces during `/gsd-new-milestone` when trigger conditions match +- Better than deferred items — triggers are checked, not forgotten + +Usage: `/gsd-plant-seed "add real-time notifications when we build the events system"` + +--- + +**`/gsd-audit-uat`** +Cross-phase audit of all outstanding UAT and verification items. +- Scans every phase for pending, skipped, blocked, and human_needed items +- Cross-references against codebase to detect stale documentation +- Produces prioritized human test plan grouped by testability +- Use before starting a new milestone to clear verification debt + +Usage: `/gsd-audit-uat` + ### Milestone Auditing **`/gsd-audit-milestone [version]`** @@ -298,7 +414,7 @@ Usage: `/gsd-plan-milestone-gaps` Configure workflow toggles and model profile interactively. - Toggle researcher, plan checker, verifier agents -- Select model profile (simple/smart/genius) +- Select model profile (simple/smart/genius/inherit) - Updates `.planning/config.json` Usage: `/gsd-settings` @@ -309,6 +425,7 @@ Quick switch model profile for GSD agents. - `quality` — Opus everywhere except verification - `balanced` — Opus for planning, Sonnet for execution (default) - `budget` — Sonnet for writing, Haiku for research/verification +- `inherit` — Use current session model for all agents (OpenCode `/model`) Usage: `/gsd-set-profile budget` diff --git a/gsd-opencode/get-shit-done/workflows/insert-phase.md b/gsd-opencode/get-shit-done/workflows/insert-phase.md index 4216120..4f37f94 100644 --- a/gsd-opencode/get-shit-done/workflows/insert-phase.md +++ b/gsd-opencode/get-shit-done/workflows/insert-phase.md @@ -1,6 +1,6 @@ - + Insert a decimal phase for urgent work discovered mid-milestone between existing integer phases. Uses decimal numbering (72.1, 72.2, etc.) to preserve the logical sequence of planned phases while accommodating urgent insertions without renumbering the entire roadmap. - + read all files referenced by the invoking prompt's execution_context before starting. diff --git a/gsd-opencode/get-shit-done/workflows/list-phase-assumptions.md b/gsd-opencode/get-shit-done/workflows/list-phase-assumptions.md index 2f5f40c..e139c50 100644 --- a/gsd-opencode/get-shit-done/workflows/list-phase-assumptions.md +++ b/gsd-opencode/get-shit-done/workflows/list-phase-assumptions.md @@ -1,8 +1,8 @@ - + Surface OpenCode's assumptions about a phase before planning, enabling users to correct misconceptions early. Key difference from discuss-phase: This is ANALYSIS of what OpenCode thinks, not INTAKE of what user knows. No file output - purely conversational to prompt discussion. - + diff --git a/gsd-opencode/get-shit-done/workflows/list-workspaces.md b/gsd-opencode/get-shit-done/workflows/list-workspaces.md new file mode 100644 index 0000000..1ce68da --- /dev/null +++ b/gsd-opencode/get-shit-done/workflows/list-workspaces.md @@ -0,0 +1,56 @@ + +List all GSD workspaces found in ~/gsd-workspaces/ with their status. + + + +read all files referenced by the invoking prompt's execution_context before starting. + + + + +## 1. Setup + +```bash +INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init list-workspaces) +if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +``` + +Parse JSON for: `workspace_base`, `workspaces`, `workspace_count`. + +## 2. Display + +**If `workspace_count` is 0:** + +``` +No workspaces found in ~/gsd-workspaces/ + +Create one with: + /gsd-new-workspace --name my-workspace --repos repo1,repo2 +``` + +Done. + +**If workspaces exist:** + +Display a table: + +``` +GSD Workspaces (~/gsd-workspaces/) + +| Name | Repos | Strategy | GSD Project | +|------|-------|----------|-------------| +| feature-a | 3 | worktree | Yes | +| feature-b | 2 | clone | No | + +Manage: + cd ~/gsd-workspaces/ # Enter a workspace + /gsd-remove-workspace # Remove a workspace +``` + +For each workspace, show: +- **Name** — directory name +- **Repos** — count from init data +- **Strategy** — from WORKSPACE.md +- **GSD Project** — whether `.planning/PROJECT.md` exists (Yes/No) + + diff --git a/gsd-opencode/get-shit-done/workflows/manager.md b/gsd-opencode/get-shit-done/workflows/manager.md new file mode 100644 index 0000000..15dcd8b --- /dev/null +++ b/gsd-opencode/get-shit-done/workflows/manager.md @@ -0,0 +1,362 @@ + + +Interactive command center for managing a milestone from a single terminal. Shows a dashboard of all phases with visual status, dispatches discuss inline and plan/execute as background agents, and loops back to the dashboard after each action. Enables parallel phase work from one terminal. + + + + + +read all files referenced by the invoking prompt's execution_context before starting. + + + + + + + +## 1. Initialize + +Bootstrap via manager init: + +```bash +INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init manager) +if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +``` + +Parse JSON for: `milestone_version`, `milestone_name`, `phase_count`, `completed_count`, `in_progress_count`, `phases`, `recommended_actions`, `all_complete`, `waiting_signal`. + +**If error:** Display the error message and exit. + +Display startup banner: + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► MANAGER +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + {milestone_version} — {milestone_name} + {phase_count} phases · {completed_count} complete + + ✓ Discuss → inline ◆ Plan/Execute → background + Dashboard auto-refreshes when background work is active. +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +Proceed to dashboard step. + + + + + +## 2. Dashboard (Refresh Point) + +**Every time this step is reached**, re-read state from disk to pick up changes from background agents: + +```bash +INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init manager) +if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +``` + +Parse the full JSON. Build the dashboard display. + +Build dashboard from JSON. Symbols: `✓` done, `◆` active, `○` pending, `·` queued. Progress bar: 20-char `█░`. + +**Status mapping** (disk_status → D P E Status): + +- `complete` → `✓ ✓ ✓` `✓ Complete` +- `partial` → `✓ ✓ ◆` `◆ Executing...` +- `planned` → `✓ ✓ ○` `○ Ready to execute` +- `discussed` → `✓ ○ ·` `○ Ready to plan` +- `researched` → `◆ · ·` `○ Ready to plan` +- `empty`/`no_directory` + `is_next_to_discuss` → `○ · ·` `○ Ready to discuss` +- `empty`/`no_directory` otherwise → `· · ·` `· Up next` +- If `is_active`, replace status icon with `◆` and append `(active)` + +If any `is_active` phases, show: `◆ Background: {action} Phase {N}, ...` above grid. + +Use `display_name` (not `name`) for the Phase column — it's pre-truncated to 20 chars with `…` if clipped. Pad all phase names to the same width for alignment. + +Use `deps_display` from init JSON for the Deps column — shows which phases this phase depends on (e.g. `1,3`) or `—` for none. + +Example output: + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► DASHBOARD +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + ████████████░░░░░░░░ 60% (3/5 phases) + ◆ Background: Planning Phase 4 + | # | Phase | Deps | D | P | E | Status | + |---|----------------------|------|---|---|---|---------------------| + | 1 | Foundation | — | ✓ | ✓ | ✓ | ✓ Complete | + | 2 | API Layer | 1 | ✓ | ✓ | ◆ | ◆ Executing (active)| + | 3 | Auth System | 1 | ✓ | ✓ | ○ | ○ Ready to execute | + | 4 | Dashboard UI & Set… | 1,2 | ✓ | ◆ | · | ◆ Planning (active) | + | 5 | Notifications | — | ○ | · | · | ○ Ready to discuss | + | 6 | Polish & Final Mail… | 1-5 | · | · | · | · Up next | +``` + +**Recommendations section:** + +If `all_complete` is true: + +``` +╔══════════════════════════════════════════════════════════════╗ +║ MILESTONE COMPLETE ║ +╚══════════════════════════════════════════════════════════════╝ + +All {phase_count} phases done. Ready for final steps: + → /gsd-verify-work — run acceptance testing + → /gsd-complete-milestone — archive and wrap up +``` + +Ask user via question: +- **question:** "All phases complete. What next?" +- **options:** "Verify work" / "Complete milestone" / "Exit manager" + +Handle responses: +- "Verify work": `skill(skill="gsd-verify-work")` then loop to dashboard. +- "Complete milestone": `skill(skill="gsd-complete-milestone")` then exit. +- "Exit manager": Go to exit step. + +**If NOT all_complete**, build compound options from `recommended_actions`: + +**Compound option logic:** Group background actions (plan/execute) together, and pair them with the single inline action (discuss) when one exists. The goal is to present the fewest options possible — one option can dispatch multiple background agents plus one inline action. + +**Building options:** + +1. Collect all background actions (execute and plan recommendations) — there can be multiple of each. +2. Collect the inline action (discuss recommendation, if any — there will be at most one since discuss is sequential). +3. Build compound options: + + **If there are ANY recommended actions (background, inline, or both):** + Create ONE primary "Continue" option that dispatches ALL of them together: + - Label: `"Continue"` — always this exact word + - Below the label, list every action that will happen. Enumerate ALL recommended actions — do not cap or truncate: + ``` + Continue: + → Execute Phase 32 (background) + → Plan Phase 34 (background) + → Discuss Phase 35 (inline) + ``` + - This dispatches all background agents first, then runs the inline discuss (if any). + - If there is no inline discuss, the dashboard refreshes after spawning background agents. + + **Important:** The Continue option must include EVERY action from `recommended_actions` — not just 2. If there are 3 actions, list 3. If there are 5, list 5. + +4. Always add: + - `"Refresh dashboard"` + - `"Exit manager"` + +Display recommendations compactly: + +``` +─────────────────────────────────────────────────────────────── +▶ Next Steps +─────────────────────────────────────────────────────────────── + +Continue: + → Execute Phase 32 (background) + → Plan Phase 34 (background) + → Discuss Phase 35 (inline) +``` + +**Auto-refresh:** If background agents are running (`is_active` is true for any phase), set a 60-second auto-refresh cycle. After presenting the action menu, if no user input is received within 60 seconds, automatically refresh the dashboard. This interval is configurable via `manager_refresh_interval` in GSD config (default: 60 seconds, set to 0 to disable). + +Present via question: +- **question:** "What would you like to do?" +- **options:** (compound options as built above + refresh + exit, question auto-adds "Other") + +**On "Other" (free text):** Parse intent — if it mentions a phase number and action, dispatch accordingly. If unclear, display available actions and loop to action_menu. + +Proceed to handle_action step with the selected action. + + + + + +## 4. Handle Action + +### Refresh Dashboard + +Loop back to dashboard step. + +### Exit Manager + +Go to exit step. + +### Compound Action (background + inline) + +When the user selects a compound option: + +1. **Spawn all background agents first** (plan/execute) — dispatch them in parallel using the Plan Phase N / Execute Phase N handlers below. +2. **Then run the inline discuss:** + +``` +skill(skill="gsd-discuss-phase", args="{PHASE_NUM}") +``` + +After discuss completes, loop back to dashboard step (background agents continue running). + +### Discuss Phase N + +Discussion is interactive — needs user input. Run inline: + +``` +skill(skill="gsd-discuss-phase", args="{PHASE_NUM}") +``` + +After discuss completes, loop back to dashboard step. + +### Plan Phase N + +Planning runs autonomously. Spawn a background agent: + +``` +task( + description="Plan phase {N}: {phase_name}", + run_in_background=true, + prompt="You are running the GSD plan-phase workflow for phase {N} of the project. + +Working directory: {cwd} +Phase: {N} — {phase_name} +Goal: {goal} + +Steps: +1. read the plan-phase workflow: cat $HOME/.config/opencode/get-shit-done/workflows/plan-phase.md +2. Run: node \"$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs\" init plan-phase {N} +3. Follow the workflow steps to produce PLAN.md files for this phase. +4. If research is enabled in config, run the research step first. +5. Spawn a gsd-planner subagent via task() to create the plans. +6. If plan-checker is enabled, spawn a gsd-plan-checker subagent to verify. +7. Commit plan files when complete. + +Important: You are running in the background. Do NOT use question — make autonomous decisions based on project context. If you hit a blocker, write it to STATE.md as a blocker and stop. Do NOT silently work around permission or file access errors — let them fail so the manager can surface them with resolution hints." +) +``` + +Display: + +``` +◆ Spawning planner for Phase {N}: {phase_name}... +``` + +Loop back to dashboard step. + +### Execute Phase N + +Execution runs autonomously. Spawn a background agent: + +``` +task( + description="Execute phase {N}: {phase_name}", + run_in_background=true, + prompt="You are running the GSD execute-phase workflow for phase {N} of the project. + +Working directory: {cwd} +Phase: {N} — {phase_name} +Goal: {goal} + +Steps: +1. read the execute-phase workflow: cat $HOME/.config/opencode/get-shit-done/workflows/execute-phase.md +2. Run: node \"$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs\" init execute-phase {N} +3. Follow the workflow steps: discover plans, analyze dependencies, group into waves. +4. For each wave, spawn gsd-executor subagents via task() to execute plans in parallel. +5. After all waves complete, spawn a gsd-verifier subagent if verifier is enabled. +6. Update ROADMAP.md and STATE.md with progress. +7. Commit all changes. + +Important: You are running in the background. Do NOT use question — make autonomous decisions. Use --no-verify on git commits. If you hit a permission error, file lock, or any access issue, do NOT work around it — let it fail and write the error to STATE.md as a blocker so the manager can surface it with resolution guidance." +) +``` + +Display: + +``` +◆ Spawning executor for Phase {N}: {phase_name}... +``` + +Loop back to dashboard step. + + + + + +## 5. Background Agent Completion + +When notified that a background agent completed: + +1. read the result message from the agent. +2. Display a brief notification: + +``` +✓ {description} + {brief summary from agent result} +``` + +3. Loop back to dashboard step. + +**If the agent reported an error or blocker:** + +Classify the error: + +**Permission / tool access error** (e.g. tool not allowed, permission denied, sandbox restriction): +- Parse the error to identify which tool or command was blocked. +- Display the error clearly, then offer to fix it: + - **question:** "Phase {N} failed — permission denied for `{tool_or_command}`. Want me to add it to settings.local.json so it's allowed?" + - **options:** "Add permission and retry" / "Run this phase inline instead" / "Skip and continue" + - "Add permission and retry": Use `skill(skill="update-config")` to add the permission to `settings.local.json`, then re-spawn the background agent. Loop to dashboard. + - "Run this phase inline instead": Dispatch the same action (plan/execute) inline via `skill()` instead of a background task. Loop to dashboard after. + - "Skip and continue": Loop to dashboard (phase stays in current state). + +**Other errors** (git lock, file conflict, logic error, etc.): +- Display the error, then offer options via question: + - **question:** "Background agent for Phase {N} encountered an issue: {error}. What next?" + - **options:** "Retry" / "Run inline instead" / "Skip and continue" / "View details" + - "Retry": Re-spawn the same background agent. Loop to dashboard. + - "Run inline instead": Dispatch the action inline via `skill()`. Loop to dashboard after. + - "Skip and continue": Loop to dashboard (phase stays in current state). + - "View details": read STATE.md blockers section, display, then re-present options. + + + + + +## 6. Exit + +Display final status with progress bar: + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► SESSION END +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + {milestone_version} — {milestone_name} + {PROGRESS_BAR} {progress_pct}% ({completed_count}/{phase_count} phases) + + Resume anytime: /gsd-manager +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +**Note:** Any background agents still running will continue to completion. Their results will be visible on next `/gsd-manager` or `/gsd-progress` invocation. + + + + + + +- [ ] Dashboard displays all phases with correct status indicators (D/P/E/V columns) +- [ ] Progress bar shows accurate completion percentage +- [ ] Dependency resolution: blocked phases show which deps are missing +- [ ] Recommendations prioritize: execute > plan > discuss +- [ ] Discuss phases run inline via skill() — interactive questions work +- [ ] Plan phases spawn background task agents — return to dashboard immediately +- [ ] Execute phases spawn background task agents — return to dashboard immediately +- [ ] Dashboard refreshes pick up changes from background agents via disk state +- [ ] Background agent completion triggers notification and dashboard refresh +- [ ] Background agent errors present retry/skip options +- [ ] All-complete state offers verify-work and complete-milestone +- [ ] Exit shows final status with resume instructions +- [ ] "Other" free-text input parsed for phase number and action +- [ ] Manager loop continues until user exits or milestone completes + diff --git a/gsd-opencode/get-shit-done/workflows/map-codebase.md b/gsd-opencode/get-shit-done/workflows/map-codebase.md index 6c1de18..0e4701c 100644 --- a/gsd-opencode/get-shit-done/workflows/map-codebase.md +++ b/gsd-opencode/get-shit-done/workflows/map-codebase.md @@ -1,10 +1,15 @@ - + Orchestrate parallel codebase mapper agents to analyze codebase and produce structured documents in .planning/codebase/ Each agent has fresh context, explores a specific focus area, and **writes documents directly**. The orchestrator only receives confirmation + line counts, then writes a summary. Output: .planning/codebase/ folder with 7 structured documents about the codebase state. - + + + +Valid GSD subagent types (use exact names — do not fall back to 'general'): +- gsd-codebase-mapper — Maps project structure and dependencies + **Why dedicated mapper agents:** @@ -28,6 +33,7 @@ Load codebase mapping context: ```bash INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init map-codebase) if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +AGENT_SKILLS_MAPPER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-codebase-mapper 2>/dev/null) ``` Extract from init JSON: `mapper_model`, `commit_docs`, `codebase_dir`, `existing_maps`, `has_maps`, `codebase_dir_exists`. @@ -82,12 +88,22 @@ mkdir -p .planning/codebase Continue to spawn_agents. - + +Before spawning agents, detect whether the current runtime supports the `task` tool for subagent delegation. + +**How to detect:** Check if you have access to a `task` tool (may be capitalized as `task` or lowercase as `task` depending on runtime). If you do NOT have a `task`/`task` tool (or only have tools like `browser_subagent` which is for web browsing, NOT code analysis): + +→ **Skip `spawn_agents` and `collect_confirmations`** — go directly to `sequential_mapping` instead. + +**CRITICAL:** Never use `browser_subagent` or `Explore` as a substitute for `task`. The `browser_subagent` tool is exclusively for web page interaction and will fail for codebase analysis. If `task` is unavailable, perform the mapping sequentially in-context. + + + Spawn 4 parallel gsd-codebase-mapper agents. Use task tool with `subagent_type="gsd-codebase-mapper"`, `model="{mapper_model}"`, and `run_in_background=true` for parallel execution. -**CRITICAL:** Use the dedicated `gsd-codebase-mapper` agent, NOT `Explore`. The mapper agent writes documents directly. +**CRITICAL:** Use the dedicated `gsd-codebase-mapper` agent, NOT `Explore` or `browser_subagent`. The mapper agent writes documents directly. **Agent 1: Tech Focus** @@ -105,7 +121,8 @@ write these documents to .planning/codebase/: - STACK.md - Languages, runtime, frameworks, dependencies, configuration - INTEGRATIONS.md - External APIs, databases, auth providers, webhooks -Explore thoroughly. write documents directly using templates. Return confirmation only." +Explore thoroughly. write documents directly using templates. Return confirmation only. +${AGENT_SKILLS_MAPPER}" ) ``` @@ -125,7 +142,8 @@ write these documents to .planning/codebase/: - ARCHITECTURE.md - Pattern, layers, data flow, abstractions, entry points - STRUCTURE.md - Directory layout, key locations, naming conventions -Explore thoroughly. write documents directly using templates. Return confirmation only." +Explore thoroughly. write documents directly using templates. Return confirmation only. +${AGENT_SKILLS_MAPPER}" ) ``` @@ -145,7 +163,8 @@ write these documents to .planning/codebase/: - CONVENTIONS.md - Code style, naming, patterns, error handling - TESTING.md - Framework, structure, mocking, coverage -Explore thoroughly. write documents directly using templates. Return confirmation only." +Explore thoroughly. write documents directly using templates. Return confirmation only. +${AGENT_SKILLS_MAPPER}" ) ``` @@ -164,7 +183,8 @@ Analyze this codebase for technical debt, known issues, and areas of concern. write this document to .planning/codebase/: - CONCERNS.md - Tech debt, bugs, security, performance, fragile areas -Explore thoroughly. write document directly using template. Return confirmation only." +Explore thoroughly. write document directly using template. Return confirmation only. +${AGENT_SKILLS_MAPPER}" ) ``` @@ -172,9 +192,19 @@ Continue to collect_confirmations. -Wait for all 4 agents to complete. +Wait for all 4 agents to complete using TaskOutput tool. -read each agent's output file to collect confirmations. +**For each agent task_id returned by the Agent tool calls above:** +``` +TaskOutput tool: + task_id: "{task_id from Agent result}" + block: true + timeout: 300000 +``` + +Call TaskOutput for all 4 agents in parallel (single message with 4 TaskOutput calls). + +Once all TaskOutput calls return, read each agent's output file to collect confirmations. **Expected confirmation format from each agent:** ``` @@ -195,6 +225,37 @@ If any agent failed, note the failure and continue with successful documents. Continue to verify_output. + +When the `task` tool is unavailable, perform codebase mapping sequentially in the current context. This replaces `spawn_agents` and `collect_confirmations`. + +**IMPORTANT:** Do NOT use `browser_subagent`, `Explore`, or any browser-based tool. Use only file system tools (read, bash, write, grep, glob, list_dir, view_file, grep_search, or equivalent tools available in your runtime). + +Perform all 4 mapping passes sequentially: + +**Pass 1: Tech Focus** +- Explore package.json/Cargo.toml/go.mod/requirements.txt, config files, dependency trees +- write `.planning/codebase/STACK.md` — Languages, runtime, frameworks, dependencies, configuration +- write `.planning/codebase/INTEGRATIONS.md` — External APIs, databases, auth providers, webhooks + +**Pass 2: Architecture Focus** +- Explore directory structure, entry points, module boundaries, data flow +- write `.planning/codebase/ARCHITECTURE.md` — Pattern, layers, data flow, abstractions, entry points +- write `.planning/codebase/STRUCTURE.md` — Directory layout, key locations, naming conventions + +**Pass 3: Quality Focus** +- Explore code style, error handling patterns, test files, CI config +- write `.planning/codebase/CONVENTIONS.md` — Code style, naming, patterns, error handling +- write `.planning/codebase/TESTING.md` — Framework, structure, mocking, coverage + +**Pass 4: Concerns Focus** +- Explore TODOs, known issues, fragile areas, security patterns +- write `.planning/codebase/CONCERNS.md` — Tech debt, bugs, security, performance, fragile areas + +Use the same document templates as the `gsd-codebase-mapper` agent. Include actual file paths formatted with backticks. + +Continue to verify_output. + + Verify all documents created successfully: @@ -307,10 +368,10 @@ End workflow. - .planning/codebase/ directory created -- 4 parallel gsd-codebase-mapper agents spawned with run_in_background=true -- Agents write documents directly (orchestrator doesn't receive document contents) -- read agent output files to collect confirmations +- If task tool available: 4 parallel gsd-codebase-mapper agents spawned with run_in_background=true +- If task tool NOT available: 4 sequential mapping passes performed inline (never using browser_subagent) - All 7 codebase documents exist +- No empty documents (each should have >20 lines) - Clear completion summary with line counts - User offered clear next steps in GSD style diff --git a/gsd-opencode/get-shit-done/workflows/milestone-summary.md b/gsd-opencode/get-shit-done/workflows/milestone-summary.md new file mode 100644 index 0000000..0cf91dd --- /dev/null +++ b/gsd-opencode/get-shit-done/workflows/milestone-summary.md @@ -0,0 +1,223 @@ +# Milestone Summary Workflow + +Generate a comprehensive, human-friendly project summary from completed milestone artifacts. +Designed for team onboarding — a new contributor can read the output and understand the entire project. + +--- + +## Step 1: Resolve Version + +```bash +VERSION="$ARGUMENTS" +``` + +If `$ARGUMENTS` is empty: +1. Check `.planning/STATE.md` for current milestone version +2. Check `.planning/milestones/` for the latest archived version +3. If neither found, check if `.planning/ROADMAP.md` exists (project may be mid-milestone) +4. If nothing found: error "No milestone found. Run /gsd-new-project or /gsd-new-milestone first." + +Set `VERSION` to the resolved version (e.g., "1.0"). + +## Step 2: Locate Artifacts + +Determine whether the milestone is **archived** or **current**: + +**Archived milestone** (`.planning/milestones/v{VERSION}-ROADMAP.md` exists): +``` +ROADMAP_PATH=".planning/milestones/v${VERSION}-ROADMAP.md" +REQUIREMENTS_PATH=".planning/milestones/v${VERSION}-REQUIREMENTS.md" +AUDIT_PATH=".planning/milestones/v${VERSION}-MILESTONE-AUDIT.md" +``` + +**Current/in-progress milestone** (no archive yet): +``` +ROADMAP_PATH=".planning/ROADMAP.md" +REQUIREMENTS_PATH=".planning/REQUIREMENTS.md" +AUDIT_PATH=".planning/v${VERSION}-MILESTONE-AUDIT.md" +``` + +Note: The audit file moves to `.planning/milestones/` on archive (per `complete-milestone` workflow). Check both locations as a fallback. + +**Always available:** +``` +PROJECT_PATH=".planning/PROJECT.md" +RETRO_PATH=".planning/RETROSPECTIVE.md" +STATE_PATH=".planning/STATE.md" +``` + +read all files that exist. Missing files are fine — the summary adapts to what's available. + +## Step 3: Discover Phase Artifacts + +Find all phase directories: + +```bash +gsd-tools.cjs init progress +``` + +This returns phase metadata. For each phase in the milestone scope: + +- read `{phase_dir}/{padded}-SUMMARY.md` if it exists — extract `one_liner`, `accomplishments`, `decisions` +- read `{phase_dir}/{padded}-VERIFICATION.md` if it exists — extract status, gaps, deferred items +- read `{phase_dir}/{padded}-CONTEXT.md` if it exists — extract key decisions from `` section +- read `{phase_dir}/{padded}-RESEARCH.md` if it exists — note what was researched + +Track which phases have which artifacts. + +**If no phase directories exist** (empty milestone or pre-build state): skip to Step 5 and generate a minimal summary noting "No phases have been executed yet." Do not error — the summary should still capture PROJECT.md and ROADMAP.md content. + +## Step 4: Gather Git Statistics + +Try each method in order until one succeeds: + +**Method 1 — Tagged milestone** (check first): +```bash +git tag -l "v${VERSION}" | head -1 +``` +If the tag exists: +```bash +git log v${VERSION} --oneline | wc -l +git diff --stat $(git log --format=%H --reverse v${VERSION} | head -1)..v${VERSION} +``` + +**Method 2 — STATE.md date range** (if no tag): +read STATE.md and extract the `started_at` or earliest session date. Use it as the `--since` boundary: +```bash +git log --oneline --since="" | wc -l +``` + +**Method 3 — Earliest phase commit** (if STATE.md has no date): +Find the earliest `.planning/phases/` commit: +```bash +git log --oneline --diff-filter=A -- ".planning/phases/" | tail -1 +``` +Use that commit's date as the start boundary. + +**Method 4 — Skip stats** (if none of the above work): +Report "Git statistics unavailable — no tag or date range could be determined." This is not an error — the summary continues without the Stats section. + +Extract (when available): +- Total commits in milestone +- Files changed, insertions, deletions +- Timeline (start date → end date) +- Contributors (from git log authors) + +## Step 5: Generate Summary Document + +write to `.planning/reports/MILESTONE_SUMMARY-v${VERSION}.md`: + +```markdown +# Milestone v{VERSION} — Project Summary + +**Generated:** {date} +**Purpose:** Team onboarding and project review + +--- + +## 1. Project Overview + +{From PROJECT.md: "What This Is", core value proposition, target users} +{If mid-milestone: note which phases are complete vs in-progress} + +## 2. Architecture & Technical Decisions + +{From CONTEXT.md files across phases: key technical choices} +{From SUMMARY.md decisions: patterns, libraries, frameworks chosen} +{From PROJECT.md: tech stack if documented} + +Present as a bulleted list of decisions with brief rationale: +- **Decision:** {what was chosen} + - **Why:** {rationale from CONTEXT.md} + - **Phase:** {which phase made this decision} + +## 3. Phases Delivered + +| Phase | Name | Status | One-Liner | +|-------|------|--------|-----------| +{For each phase: number, name, status (complete/in-progress/planned), one_liner from SUMMARY.md} + +## 4. Requirements Coverage + +{From REQUIREMENTS.md: list each requirement with status} +- ✅ {Requirement met} +- ⚠️ {Requirement partially met — note gap} +- ❌ {Requirement not met — note reason} + +{If MILESTONE-AUDIT.md exists: include audit verdict} + +## 5. Key Decisions Log + +{Aggregate from all CONTEXT.md sections} +{Each decision with: ID, description, phase, rationale} + +## 6. Tech Debt & Deferred Items + +{From VERIFICATION.md files: gaps found, anti-patterns noted} +{From RETROSPECTIVE.md: lessons learned, what to improve} +{From CONTEXT.md sections: ideas parked for later} + +## 7. Getting Started + +{Entry points for new contributors:} +- **Run the project:** {from PROJECT.md or SUMMARY.md} +- **Key directories:** {from codebase structure} +- **Tests:** {test command from PROJECT.md or AGENTS.md} +- **Where to look first:** {main entry points, core modules} + +--- + +## Stats + +- **Timeline:** {start} → {end} ({duration}) +- **Phases:** {count complete} / {count total} +- **Commits:** {count} +- **Files changed:** {count} (+{insertions} / -{deletions}) +- **Contributors:** {list} +``` + +## Step 6: write and Commit + +**Overwrite guard:** If `.planning/reports/MILESTONE_SUMMARY-v${VERSION}.md` already exists, ask the user: +> "A milestone summary for v{VERSION} already exists. Overwrite it, or view the existing one?" +If "view": display existing file and skip to Step 8 (interactive mode). If "overwrite": proceed. + +Create the reports directory if needed: +```bash +mkdir -p .planning/reports +``` + +write the summary, then commit: +```bash +gsd-tools.cjs commit "docs(v${VERSION}): generate milestone summary for onboarding" \ + --files ".planning/reports/MILESTONE_SUMMARY-v${VERSION}.md" +``` + +## Step 7: Present Summary + +Display the full summary document inline. + +## Step 8: Offer Interactive Mode + +After presenting the summary: + +> "Summary written to `.planning/reports/MILESTONE_SUMMARY-v{VERSION}.md`. +> +> I have full context from the build artifacts. Want to ask anything about the project? +> Architecture decisions, specific phases, requirements, tech debt — ask away." + +If the user asks questions: +- Answer from the artifacts already loaded (CONTEXT.md, SUMMARY.md, VERIFICATION.md, etc.) +- Reference specific files and decisions +- Stay grounded in what was actually built (not speculation) + +If the user is done: +- Suggest next steps: `/gsd-new-milestone`, `/gsd-progress`, or sharing the summary with the team + +## Step 9: Update STATE.md + +```bash +gsd-tools.cjs state record-session \ + --stopped-at "Milestone v${VERSION} summary generated" \ + --resume-file ".planning/reports/MILESTONE_SUMMARY-v${VERSION}.md" +``` diff --git a/gsd-opencode/get-shit-done/workflows/new-milestone.md b/gsd-opencode/get-shit-done/workflows/new-milestone.md index 3514b64..3d7e773 100644 --- a/gsd-opencode/get-shit-done/workflows/new-milestone.md +++ b/gsd-opencode/get-shit-done/workflows/new-milestone.md @@ -1,8 +1,8 @@ - + Start a new milestone cycle for an existing project. Loads project context, gathers milestone goals (from MILESTONE-CONTEXT.md or conversation), updates PROJECT.md and STATE.md, optionally runs parallel research, defines scoped requirements with REQ-IDs, spawns the roadmapper to create phased execution plan, and commits all artifacts. Brownfield equivalent of new-project. - + @@ -10,10 +10,23 @@ read all files referenced by the invoking prompt's execution_context before star + +Valid GSD subagent types (use exact names — do not fall back to 'general'): +- gsd-project-researcher — Researches project-level technical decisions +- gsd-research-synthesizer — Synthesizes findings from parallel research agents +- gsd-roadmapper — Creates phased execution roadmaps + + ## 1. Load Context +Parse `$ARGUMENTS` before doing anything else: +- `--reset-phase-numbers` flag → opt into restarting roadmap phase numbering at `1` +- remaining text → use as milestone name if present + +If the flag is absent, keep the current behavior of continuing phase numbering from the previous milestone. + - read PROJECT.md (existing project, validated requirements, decisions) - read MILESTONES.md (what shipped previously) - read STATE.md (pending todos, blockers) @@ -37,6 +50,38 @@ read all files referenced by the invoking prompt's execution_context before star - Suggest next version (v1.0 → v1.1, or v2.0 for major) - Confirm with user +## 3.5. Verify Milestone Understanding + +Before writing any files, present a summary of what was gathered and ask for confirmation. + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► MILESTONE SUMMARY +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +**Milestone v[X.Y]: [Name]** + +**Goal:** [One sentence] + +**Target features:** +- [Feature 1] +- [Feature 2] +- [Feature 3] + +**Key context:** [Any important constraints, decisions, or notes from questioning] +``` + +question: +- header: "Confirm?" +- question: "Does this capture what you want to build in this milestone?" +- options: + - "Looks good" — Proceed to write PROJECT.md + - "Adjust" — Let me correct or add details + +**If "Adjust":** Ask what needs changing (plain text, NOT question). Incorporate changes, re-present the summary. Loop until "Looks good" is selected. + +**If "Looks good":** Proceed to Step 4. + ## 4. Update PROJECT.md Add/update: @@ -54,6 +99,27 @@ Add/update: Update Active requirements section and "Last updated" footer. +Ensure the `## Evolution` section exists in PROJECT.md. If missing (projects created before this feature), add it before the footer: + +```markdown +## Evolution + +This document evolves at phase transitions and milestone boundaries. + +**After each phase transition** (via `/gsd-transition`): +1. Requirements invalidated? → Move to Out of Scope with reason +2. Requirements validated? → Move to Validated with phase reference +3. New requirements emerged? → Add to Active +4. Decisions to log? → Add to Key Decisions +5. "What This Is" still accurate? → Update if drifted + +**After each milestone** (via `/gsd-complete-milestone`): +1. Full review of all sections +2. Core Value check — still the right priority? +3. Audit Out of Scope — reasons still valid? +4. Update Context with current state +``` + ## 5. Update STATE.md ```markdown @@ -80,27 +146,52 @@ node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: star ```bash INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init new-milestone) if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +AGENT_SKILLS_RESEARCHER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-project-researcher 2>/dev/null) +AGENT_SKILLS_SYNTHESIZER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-synthesizer 2>/dev/null) +AGENT_SKILLS_ROADMAPPER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-roadmapper 2>/dev/null) +``` + +Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`, `latest_completed_milestone`, `phase_dir_count`, `phase_archive_path`. + +## 7.5 Reset-phase safety (only when `--reset-phase-numbers`) + +If `--reset-phase-numbers` is active: + +1. Set starting phase number to `1` for the upcoming roadmap. +2. If `phase_dir_count > 0`, archive the old phase directories before roadmapping so new `01-*` / `02-*` directories cannot collide with stale milestone directories. + +If `phase_dir_count > 0` and `phase_archive_path` is available: + +```bash +mkdir -p "${phase_archive_path}" +find .planning/phases -mindepth 1 -maxdepth 1 -type d -exec mv {} "${phase_archive_path}/" \; ``` -Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`. +Then verify `.planning/phases/` no longer contains old milestone directories before continuing. + +If `phase_dir_count > 0` but `phase_archive_path` is missing: +- Stop and explain that reset numbering is unsafe without a completed milestone archive target. +- Tell the user to complete/archive the previous milestone first, then rerun `/gsd-new-milestone --reset-phase-numbers ${GSD_WS}`. ## 8. Research Decision +Check `research_enabled` from init JSON (loaded from config). + +**If `research_enabled` is `true`:** + question: "Research the domain ecosystem for new features before defining requirements?" - "Research first (Recommended)" — Discover patterns, features, architecture for NEW capabilities -- "Skip research" — Go straight to requirements +- "Skip research for this milestone" — Go straight to requirements (does not change your default) -**Persist choice to config** (so future `/gsd-plan-phase` honors it): +**If `research_enabled` is `false`:** -```bash -# If "Research first": persist true -node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-set workflow.research true +question: "Research the domain ecosystem for new features before defining requirements?" +- "Skip research (current default)" — Go straight to requirements +- "Research first" — Discover patterns, features, architecture for NEW capabilities -# If "Skip research": persist false -node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-set workflow.research false -``` +**IMPORTANT:** Do NOT persist this choice to config.json. The `workflow.research` setting is a persistent user preference that controls plan-phase behavior across the project. Changing it here would silently alter future `/gsd-plan-phase` behavior. To change the default, use `/gsd-settings`. -**If "Research first":** +**If user chose "Research first":** ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ @@ -134,6 +225,8 @@ Focus ONLY on what's needed for the NEW features. - .planning/PROJECT.md (Project context) +${AGENT_SKILLS_RESEARCHER} + {CONSUMER} {GATES} @@ -168,6 +261,8 @@ Synthesize research outputs into SUMMARY.md. - .planning/research/PITFALLS.md +${AGENT_SKILLS_SYNTHESIZER} + write to: .planning/research/SUMMARY.md Use template: $HOME/.config/opencode/get-shit-done/templates/research-project/SUMMARY.md Commit after writing. @@ -268,7 +363,9 @@ node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: defi ◆ Spawning roadmapper... ``` -**Starting phase number:** read MILESTONES.md for last phase number. Continue from there (v1.0 ended at phase 5 → v1.1 starts at phase 6). +**Starting phase number:** +- If `--reset-phase-numbers` is active, start at **Phase 1** +- Otherwise, continue from the previous milestone's last phase number (v1.0 ended at phase 5 → v1.1 starts at phase 6) ``` task(prompt=" @@ -280,11 +377,16 @@ task(prompt=" - .planning/config.json - .planning/MILESTONES.md + +${AGENT_SKILLS_ROADMAPPER} + Create roadmap for milestone v[X.Y]: -1. Start phase numbering from [N] +1. Respect the selected numbering mode: + - `--reset-phase-numbers` → start at Phase 1 + - default behavior → continue from the previous milestone's last phase number 2. Derive phases from THIS MILESTONE's requirements only 3. Map every requirement to exactly one phase 4. Derive 2-5 success criteria per phase (observable user behaviors) @@ -357,11 +459,11 @@ node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: crea **Phase [N]: [Phase Name]** — [Goal] -`/gsd-discuss-phase [N]` — gather context and clarify approach +`/gsd-discuss-phase [N] ${GSD_WS}` — gather context and clarify approach *`/new` first → fresh context window* -Also: `/gsd-plan-phase [N]` — skip discussion, plan directly +Also: `/gsd-plan-phase [N] ${GSD_WS}` — skip discussion, plan directly ``` @@ -376,9 +478,9 @@ Also: `/gsd-plan-phase [N]` — skip discussion, plan directly - [ ] gsd-roadmapper spawned with phase numbering context - [ ] Roadmap files written immediately (not draft) - [ ] User feedback incorporated (if any) -- [ ] ROADMAP.md phases continue from previous milestone +- [ ] Phase numbering mode respected (continued or reset) - [ ] All commits made (if planning docs committed) -- [ ] User knows next step: `/gsd-discuss-phase [N]` +- [ ] User knows next step: `/gsd-discuss-phase [N] ${GSD_WS}` **Atomic commits:** Each phase commits its artifacts immediately. diff --git a/gsd-opencode/get-shit-done/workflows/new-project.md b/gsd-opencode/get-shit-done/workflows/new-project.md index 50fbbaf..b70bb22 100644 --- a/gsd-opencode/get-shit-done/workflows/new-project.md +++ b/gsd-opencode/get-shit-done/workflows/new-project.md @@ -1,17 +1,26 @@ - + Initialize a new project through unified flow: questioning, research (optional), requirements, roadmap. This is the most leveraged moment in any project — deep questioning here means better plans, better execution, better outcomes. One workflow takes you from idea to ready-for-planning. - + read all files referenced by the invoking prompt's execution_context before starting. + +Valid GSD subagent types (use exact names — do not fall back to 'general'): +- gsd-project-researcher — Researches project-level technical decisions +- gsd-research-synthesizer — Synthesizes findings from parallel research agents +- gsd-roadmapper — Creates phased execution roadmaps + + + ## Auto Mode Detection Check if `--auto` flag is present in $ARGUMENTS. **If auto mode:** + - Skip brownfield mapping offer (assume greenfield) - Skip deep questioning (extract context from provided document) - Config: YOLO mode is implicit (skip that question), but ask granularity/git/agents FIRST (Step 2a) @@ -23,6 +32,7 @@ Check if `--auto` flag is present in $ARGUMENTS. **Document requirement:** Auto mode requires an idea document — either: + - File reference: `/gsd-new-project --auto @prd.md` - Pasted/written text in the prompt @@ -37,6 +47,7 @@ Usage: The document should describe what you want to build. ``` + @@ -48,6 +59,9 @@ The document should describe what you want to build. ```bash INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init new-project) if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +AGENT_SKILLS_RESEARCHER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-project-researcher 2>/dev/null) +AGENT_SKILLS_SYNTHESIZER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-synthesizer 2>/dev/null) +AGENT_SKILLS_ROADMAPPER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-roadmapper 2>/dev/null) ``` Parse JSON for: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `project_exists`, `has_codebase_map`, `planning_exists`, `has_existing_code`, `has_package_file`, `is_brownfield`, `needs_codebase_map`, `has_git`, `project_path`. @@ -55,6 +69,7 @@ Parse JSON for: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `co **If `project_exists` is true:** Error — project already initialized. Use `/gsd-progress`. **If `has_git` is false:** Initialize git: + ```bash git init ``` @@ -66,6 +81,7 @@ git init **If `needs_codebase_map` is true** (from init — existing code detected but no codebase map): Use question: + - header: "Codebase" - question: "I detected existing code in this directory. Would you like to map the codebase first?" - options: @@ -73,9 +89,11 @@ Use question: - "Skip mapping" — Proceed with project initialization **If "Map codebase first":** + ``` Run `/gsd-map-codebase` first, then return to `/gsd-new-project` ``` + Exit command. **If "Skip mapping" OR `needs_codebase_map` is false:** Continue to Step 3. @@ -159,29 +177,18 @@ question([ options: [ { label: "Smart (Recommended)", description: "Two models: one for reseach and planing, other for execution and verification" }, { label: "Simple", description: Description: "One model for all agents (not flexible)" }, - { label: "Genius (most flexible)", description: "Three models: different for every stage" } + { label: "Genius (most flexible)", description: "Three models: different for every stage" }, + { label: "Inherit", description: "Use the current session model for all agents (OpenCode /model)" } ] } ]) ``` -Create `.planning/config.json` with mode set to "yolo": - -```json -{ - "mode": "yolo", - "granularity": "[selected]", - "parallelization": true|false, - "commit_docs": true|false, - "model_profile": "simple|smart|genius", - "workflow": { - "research": true|false, - "plan_check": true|false, - "verifier": true|false, - "nyquist_validation": depth !== "quick", - "auto_advance": true - } -} +Create `.planning/config.json` with all settings (CLI fills in remaining defaults automatically): + +```bash +mkdir -p .planning +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-new-project '{"mode":"yolo","granularity":"[selected]","parallelization":true|false,"commit_docs":true|false,"model_profile":"simple|smart|genius|inherit","workflow":{"research":true|false,"plan_check":true|false,"verifier":true|false,"nyquist_validation":true|false,"auto_advance":true}}' ``` **If commit_docs = No:** Add `.planning/` to `.gitignore`. @@ -221,11 +228,20 @@ Ask inline (freeform, NOT question): Wait for their response. This gives you the context needed to ask intelligent follow-up questions. +**Research-before-questions mode:** Check if `workflow.research_before_questions` is enabled in `.planning/config.json` (or the config from init context). When enabled, before asking follow-up questions about a topic area: + +1. Do a brief web search for best practices related to what the user described +2. Mention key findings naturally as you ask questions (e.g., "Most projects like this use X — is that what you're thinking, or something different?") +3. This makes questions more informed without changing the conversational flow + +When disabled (default), ask questions directly as before. + **Follow the thread:** Based on what they said, ask follow-up questions that dig into their response. Use question with options that probe what they mentioned — interpretations, clarifications, concrete examples. Keep following threads. Each answer opens new threads to explore. Ask about: + - What excited them - What problem sparked this - What they mean by vague terms @@ -233,6 +249,7 @@ Keep following threads. Each answer opens new threads to explore. Ask about: - What's already decided Consult `questioning.md` for techniques: + - Challenge vagueness - Make abstract concrete - Surface assumptions @@ -334,6 +351,27 @@ Initialize with any decisions made during questioning: *Last updated: [date] after initialization* ``` +**Evolution section** (include at the end of PROJECT.md, before the footer): + +```markdown +## Evolution + +This document evolves at phase transitions and milestone boundaries. + +**After each phase transition** (via `/gsd-transition`): +1. Requirements invalidated? → Move to Out of Scope with reason +2. Requirements validated? → Move to Validated with phase reference +3. New requirements emerged? → Add to Active +4. Decisions to log? → Add to Key Decisions +5. "What This Is" still accurate? → Update if drifted + +**After each milestone** (via `/gsd-complete-milestone`): +1. Full review of all sections +2. Core Value check — still the right priority? +3. Audit Out of Scope — reasons still valid? +4. Update Context with current state +``` + Do not compress. Capture everything gathered. **Commit PROJECT.md:** @@ -459,35 +497,29 @@ questions: [ options: [ { label: "Smart (Recommended)", description: "Two models: one for reseach and planing, other for execution and verification" }, { label: "Simple", description: Description: "One model for all agents (not flexible)" }, - { label: "Genius (most flexible)", description: "Three models: different for every stage" } + { label: "Genius (most flexible)", description: "Three models: different for every stage" }, + { label: "Inherit", description: "Use the current session model for all agents (OpenCode /model)" } ] } ] ``` -Create `.planning/config.json` with all settings: - -```json -{ - "mode": "yolo|interactive", - "granularity": "coarse|standard|fine", - "parallelization": true|false, - "commit_docs": true|false, - "model_profile": "simple|smart|genius", - "workflow": { - "research": true|false, - "plan_check": true|false, - "verifier": true|false, - "nyquist_validation": depth !== "quick" - } -} +Create `.planning/config.json` with all settings (CLI fills in remaining defaults automatically): + +```bash +mkdir -p .planning +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-new-project '{"mode":"[yolo|interactive]","granularity":"[selected]","parallelization":true|false,"commit_docs":true|false,"model_profile":"simple|smart|genius|inherit","workflow":{"research":true|false,"plan_check":true|false,"verifier":true|false,"nyquist_validation":[false if granularity=coarse, true otherwise]}}' ``` +**Note:** Run `/gsd-settings` anytime to update model profile, workflow agents, branching strategy, and other preferences. + **If commit_docs = No:** + - Set `commit_docs: false` in config.json - Add `.planning/` to `.gitignore` (create if needed) **If commit_docs = Yes:** + - No additional gitignore entries needed **Commit config.json:** @@ -496,7 +528,37 @@ Create `.planning/config.json` with all settings: node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "chore: add project config" --files .planning/config.json ``` -**Note:** Run `/gsd-settings` anytime to update these preferences. +## 5.1. Sub-Repo Detection + +**Detect multi-repo workspace:** + +Check for directories with their own `.git` folders (separate repos within the workspace): + +```bash +find . -maxdepth 1 -type d -not -name ".*" -not -name "node_modules" -exec test -d "{}/.git" \; -print +``` + +**If sub-repos found:** + +Strip the `./` prefix to get directory names (e.g., `./backend` → `backend`). + +Use question: + +- header: "Multi-Repo Workspace" +- question: "I detected separate git repos in this workspace. Which directories contain code that GSD should commit to?" +- multiSelect: true +- options: one option per detected directory + - "[directory name]" — Separate git repo + +**If user selects one or more directories:** + +- Set `planning.sub_repos` in config.json to the selected directory names array (e.g., `["backend", "frontend"]`) +- Auto-set `planning.commit_docs` to `false` (planning docs stay local in multi-repo workspaces) +- Add `.planning/` to `.gitignore` if not already present + +Config changes are saved locally — no commit needed since `commit_docs` is `false` in multi-repo mode. + +**If no sub-repos found or user selects none:** Continue with no changes to config. ## 5.5. Resolve Model Profile @@ -507,6 +569,7 @@ Use models from init: `researcher_model`, `synthesizer_model`, `roadmapper_model **If auto mode:** Default to "Research first" without asking. Use question: + - header: "Research" - question: "Research the domain ecosystem before defining requirements?" - options: @@ -516,6 +579,7 @@ Use question: **If "Research first":** Display stage banner: + ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► RESEARCHING @@ -525,6 +589,7 @@ Researching [domain] ecosystem... ``` Create research directory: + ```bash mkdir -p .planning/research ``` @@ -532,10 +597,12 @@ mkdir -p .planning/research **Determine milestone context:** Check if this is greenfield or subsequent milestone: + - If no "Validated" requirements in PROJECT.md → Greenfield (building from scratch) - If "Validated" requirements exist → Subsequent milestone (adding to existing app) Display spawning indicator: + ``` ◆ Spawning 4 researchers in parallel... → Stack research @@ -566,6 +633,8 @@ What's the standard 2025 stack for [domain]? - {project_path} (Project context and goals) +${AGENT_SKILLS_RESEARCHER} + Your STACK.md feeds into roadmap creation. Be prescriptive: - Specific libraries with versions @@ -604,6 +673,8 @@ What features do [domain] products have? What's table stakes vs differentiating? - {project_path} (Project context) +${AGENT_SKILLS_RESEARCHER} + Your FEATURES.md feeds into requirements definition. Categorize clearly: - Table stakes (must have or users leave) @@ -642,6 +713,8 @@ How are [domain] systems typically structured? What are major components? - {project_path} (Project context) +${AGENT_SKILLS_RESEARCHER} + Your ARCHITECTURE.md informs phase structure in roadmap. Include: - Component boundaries (what talks to what) @@ -680,6 +753,8 @@ What do [domain] projects commonly get wrong? Critical mistakes? - {project_path} (Project context) +${AGENT_SKILLS_RESEARCHER} + Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall: - Warning signs (how to detect early) @@ -715,6 +790,8 @@ Synthesize research outputs into SUMMARY.md. - .planning/research/PITFALLS.md +${AGENT_SKILLS_SYNTHESIZER} + write to: .planning/research/SUMMARY.md Use template: $HOME/.config/opencode/get-shit-done/templates/research-project/SUMMARY.md @@ -724,6 +801,7 @@ Commit after writing. ``` Display research complete banner and key findings: + ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► RESEARCH COMPLETE ✓ @@ -743,6 +821,7 @@ Files: `.planning/research/` ## 7. Define Requirements Display stage banner: + ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► DEFINING REQUIREMENTS @@ -752,6 +831,7 @@ Display stage banner: **Load context:** read PROJECT.md and extract: + - Core value (the ONE thing that must work) - Stated constraints (budget, timeline, tech limitations) - Any explicit scope boundaries @@ -759,6 +839,7 @@ read PROJECT.md and extract: **If research exists:** read research/FEATURES.md and extract feature categories. **If auto mode:** + - Auto-include all table stakes features (users expect these) - Include features explicitly mentioned in provided document - Auto-defer differentiators not mentioned in document @@ -797,6 +878,7 @@ Here are the features for [domain]: Ask: "What are the main things users need to be able to do?" For each capability mentioned: + - Ask clarifying questions to make it specific - Probe for related capabilities - Group into categories @@ -815,6 +897,7 @@ For each category, use question: - "None for v1" — Defer entire category Track responses: + - Selected features → v1 requirements - Unselected table stakes → v2 (users expect these) - Unselected differentiators → out of scope @@ -822,6 +905,7 @@ Track responses: **Identify gaps:** Use question: + - header: "Additions" - question: "Any requirements research missed? (Features specific to your vision)" - options: @@ -835,6 +919,7 @@ Cross-check requirements against Core Value from PROJECT.md. If gaps detected, s **Generate REQUIREMENTS.md:** Create `.planning/REQUIREMENTS.md` with: + - v1 Requirements grouped by category (checkboxes, REQ-IDs) - v2 Requirements (deferred) - Out of Scope (explicit exclusions with reasoning) @@ -845,12 +930,14 @@ Create `.planning/REQUIREMENTS.md` with: **Requirement quality criteria:** Good requirements are: + - **Specific and testable:** "User can reset password via email link" (not "Handle password reset") - **User-centric:** "User can X" (not "System does Y") - **Atomic:** One capability per requirement (not "User can login and manage profile") - **Independent:** Minimal dependencies on other requirements Reject vague requirements. Push for specificity: + - "Handle authentication" → "User can log in with email/password and stay logged in across sessions" - "Support sharing" → "User can share post via link that opens in recipient's browser" @@ -888,6 +975,7 @@ node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: defi ## 8. Create Roadmap Display stage banner: + ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► CREATING ROADMAP @@ -909,6 +997,8 @@ task(prompt=" - .planning/config.json (Granularity and mode settings) +${AGENT_SKILLS_ROADMAPPER} + @@ -928,6 +1018,7 @@ write files first, then return. This ensures artifacts persist even if context i **Handle roadmapper return:** **If `## ROADMAP BLOCKED`:** + - Present blocker information - Work with user to resolve - Re-spawn when resolved @@ -977,6 +1068,7 @@ Success criteria: **CRITICAL: Ask for approval before committing (interactive mode only):** Use question: + - header: "Roadmap" - question: "Does this roadmap structure work for you?" - options: @@ -987,8 +1079,10 @@ Use question: **If "Approve":** Continue to commit. **If "Adjust phases":** + - Get user's adjustment notes - Re-spawn roadmapper with revision context: + ``` task(prompt=" @@ -999,20 +1093,31 @@ Use question: - .planning/ROADMAP.md (Current roadmap to revise) + ${AGENT_SKILLS_ROADMAPPER} + Update the roadmap based on feedback. edit files in place. Return ROADMAP REVISED with changes made. ", subagent_type="gsd-roadmapper", model="{roadmapper_model}", description="Revise roadmap") ``` + - Present revised roadmap - Loop until user approves **If "Review full file":** Display raw `cat .planning/ROADMAP.md`, then re-ask. +**Generate or refresh project AGENTS.md before final commit:** + +```bash +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" generate-OpenCode-md +``` + +This ensures new projects get the default GSD workflow-enforcement guidance and current project context in `AGENTS.md`. + **Commit roadmap (after approval or auto mode):** ```bash -node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: create roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: create roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md AGENTS.md ``` ## 9. Done @@ -1033,6 +1138,7 @@ Present completion summary: | Research | `.planning/research/` | | Requirements | `.planning/REQUIREMENTS.md` | | Roadmap | `.planning/ROADMAP.md` | +| Project guide | `AGENTS.md` | **[N] phases** | **[X] requirements** | Ready to build ✓ ``` @@ -1049,6 +1155,37 @@ Exit skill and invoke command("/gsd-discuss-phase 1 --auto") **If interactive mode:** +Check if Phase 1 has UI indicators (look for `**UI hint**: yes` in Phase 1 detail section of ROADMAP.md): + +```bash +PHASE1_SECTION=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase 1 2>/dev/null) +PHASE1_HAS_UI=$(echo "$PHASE1_SECTION" | grep -qi "UI hint.*yes" && echo "true" || echo "false") +``` + +**If Phase 1 has UI (`PHASE1_HAS_UI` is `true`):** + +``` +─────────────────────────────────────────────────────────────── + +## ▶ Next Up + +**Phase 1: [Phase Name]** — [Goal from ROADMAP.md] + +/gsd-discuss-phase 1 — gather context and clarify approach + +*/new first → fresh context window* + +--- + +**Also available:** +- /gsd-ui-phase 1 — generate UI design contract (recommended for frontend phases) +- /gsd-plan-phase 1 — skip discussion, plan directly + +─────────────────────────────────────────────────────────────── +``` + +**If Phase 1 has no UI:** + ``` ─────────────────────────────────────────────────────────────── @@ -1083,6 +1220,7 @@ Exit skill and invoke command("/gsd-discuss-phase 1 --auto") - `.planning/REQUIREMENTS.md` - `.planning/ROADMAP.md` - `.planning/STATE.md` +- `AGENTS.md` @@ -1104,6 +1242,7 @@ Exit skill and invoke command("/gsd-discuss-phase 1 --auto") - [ ] ROADMAP.md created with phases, requirement mappings, success criteria - [ ] STATE.md initialized - [ ] REQUIREMENTS.md traceability updated +- [ ] AGENTS.md generated with GSD workflow guidance - [ ] User knows next step is `/gsd-discuss-phase 1` **Atomic commits:** Each phase commits its artifacts immediately. If context is lost, artifacts persist. diff --git a/gsd-opencode/get-shit-done/workflows/new-workspace.md b/gsd-opencode/get-shit-done/workflows/new-workspace.md new file mode 100644 index 0000000..3b3f90f --- /dev/null +++ b/gsd-opencode/get-shit-done/workflows/new-workspace.md @@ -0,0 +1,237 @@ + +Create an isolated workspace directory with git repo copies (worktrees or clones) and an independent `.planning/` directory. Supports multi-repo orchestration and single-repo feature branch isolation. + + + +read all files referenced by the invoking prompt's execution_context before starting. + + + + +## 1. Setup + +**MANDATORY FIRST STEP — Execute init command:** + +```bash +INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init new-workspace) +if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +``` + +Parse JSON for: `default_workspace_base`, `child_repos`, `child_repo_count`, `worktree_available`, `is_git_repo`, `cwd_repo_name`, `project_root`. + +## 2. Parse Arguments + +Extract from $ARGUMENTS: +- `--name` → `WORKSPACE_NAME` (required) +- `--repos` → `REPO_LIST` (comma-separated paths or names) +- `--path` → `TARGET_PATH` (defaults to `$default_workspace_base/$WORKSPACE_NAME`) +- `--strategy` → `STRATEGY` (defaults to `worktree`) +- `--branch` → `BRANCH_NAME` (defaults to `workspace/$WORKSPACE_NAME`) +- `--auto` → skip interactive questions + +**If `--name` is missing and not `--auto`:** + +Use question: +- header: "Workspace Name" +- question: "What should this workspace be called?" +- requireAnswer: true + +## 3. Select Repos + +**If `--repos` is provided:** Parse comma-separated values. For each value: +- If it's an absolute path, use it directly +- If it's a relative path or name, resolve against `$project_root` +- Special case: `.` means current repo (use `$project_root`, name it `$cwd_repo_name`) + +**If `--repos` is NOT provided and not `--auto`:** + +**If `child_repo_count` > 0:** + +Present child repos for selection: + +Use question: +- header: "Select Repos" +- question: "Which repos should be included in the workspace?" +- options: List each child repo from `child_repos` array by name +- multiSelect: true + +**If `child_repo_count` is 0 and `is_git_repo` is true:** + +Use question: +- header: "Current Repo" +- question: "No child repos found. Create a workspace with the current repo?" +- options: + - "Yes — create workspace with current repo" → use current repo + - "Cancel" → exit + +**If `child_repo_count` is 0 and `is_git_repo` is false:** + +Error: +``` +No git repos found in the current directory and this is not a git repo. + +Run this command from a directory containing git repos, or specify repos explicitly: + /gsd-new-workspace --name my-workspace --repos /path/to/repo1,/path/to/repo2 +``` +Exit. + +**If `--auto` and `--repos` is NOT provided:** + +Error: +``` +Error: --auto requires --repos to specify which repos to include. + +Usage: + /gsd-new-workspace --name my-workspace --repos repo1,repo2 --auto +``` +Exit. + +## 4. Select Strategy + +**If `--strategy` is provided:** Use it (validate: must be `worktree` or `clone`). + +**If `--strategy` is NOT provided and not `--auto`:** + +Use question: +- header: "Strategy" +- question: "How should repos be copied into the workspace?" +- options: + - "Worktree (recommended) — lightweight, shares .git objects with source repo" → `worktree` + - "Clone — fully independent copy, no connection to source repo" → `clone` + +**If `--auto`:** Default to `worktree`. + +## 5. Validate + +Before creating anything, validate: + +1. **Target path** — must not exist or must be empty: +```bash +if [ -d "$TARGET_PATH" ] && [ "$(ls -A "$TARGET_PATH" 2>/dev/null)" ]; then + echo "Error: Target path already exists and is not empty: $TARGET_PATH" + echo "Choose a different --name or --path." + exit 1 +fi +``` + +2. **Source repos exist and are git repos** — for each repo path: +```bash +if [ ! -d "$REPO_PATH/.git" ]; then + echo "Error: Not a git repo: $REPO_PATH" + exit 1 +fi +``` + +3. **Worktree availability** — if strategy is `worktree` and `worktree_available` is false: +``` +Error: git is not available. Install git or use --strategy clone. +``` + +Report all validation errors at once, not one at a time. + +## 6. Create Workspace + +```bash +mkdir -p "$TARGET_PATH" +``` + +### For each repo: + +**Worktree strategy:** +```bash +cd "$SOURCE_REPO_PATH" +git worktree add "$TARGET_PATH/$REPO_NAME" -b "$BRANCH_NAME" 2>&1 +``` + +If `git worktree add` fails because the branch already exists, try with a timestamped branch: +```bash +TIMESTAMP=$(date +%Y%m%d%H%M%S) +git worktree add "$TARGET_PATH/$REPO_NAME" -b "${BRANCH_NAME}-${TIMESTAMP}" 2>&1 +``` + +If that also fails, report the error and continue with remaining repos. + +**Clone strategy:** +```bash +git clone "$SOURCE_REPO_PATH" "$TARGET_PATH/$REPO_NAME" 2>&1 +cd "$TARGET_PATH/$REPO_NAME" +git checkout -b "$BRANCH_NAME" 2>&1 +``` + +Track results: which repos succeeded, which failed, what branch was used. + +## 7. write WORKSPACE.md + +write the workspace manifest at `$TARGET_PATH/WORKSPACE.md`: + +```markdown +# Workspace: $WORKSPACE_NAME + +Created: $DATE +Strategy: $STRATEGY + +## Member Repos + +| Repo | Source | Branch | Strategy | +|------|--------|--------|----------| +| $REPO_NAME | $SOURCE_PATH | $BRANCH | $STRATEGY | +...for each repo... + +## Notes + +[Add context about what this workspace is for] +``` + +## 8. Initialize .planning/ + +```bash +mkdir -p "$TARGET_PATH/.planning" +``` + +## 9. Report and Next Steps + +**If all repos succeeded:** + +``` +Workspace created: $TARGET_PATH + + Repos: $REPO_COUNT + Strategy: $STRATEGY + Branch: $BRANCH_NAME + +Next steps: + cd $TARGET_PATH + /gsd-new-project # Initialize GSD in the workspace +``` + +**If some repos failed:** + +``` +Workspace created with $SUCCESS_COUNT of $TOTAL_COUNT repos: $TARGET_PATH + + Succeeded: repo1, repo2 + Failed: repo3 (branch already exists), repo4 (not a git repo) + +Next steps: + cd $TARGET_PATH + /gsd-new-project # Initialize GSD in the workspace +``` + +**Offer to initialize GSD (if not `--auto`):** + +Use question: +- header: "Initialize GSD" +- question: "Would you like to initialize a GSD project in the new workspace?" +- options: + - "Yes — run /gsd-new-project" → tell user to `cd $TARGET_PATH` first, then run `/gsd-new-project` + - "No — I'll set it up later" → done + + + + +- [ ] Workspace directory created at target path +- [ ] All specified repos copied (worktree or clone) into workspace +- [ ] WORKSPACE.md manifest written with correct repo table +- [ ] `.planning/` directory initialized at workspace root +- [ ] User informed of workspace path and next steps + diff --git a/gsd-opencode/get-shit-done/workflows/next.md b/gsd-opencode/get-shit-done/workflows/next.md new file mode 100644 index 0000000..18b7c21 --- /dev/null +++ b/gsd-opencode/get-shit-done/workflows/next.md @@ -0,0 +1,97 @@ + +Detect current project state and automatically advance to the next logical GSD workflow step. +Reads project state to determine: discuss → plan → execute → verify → complete progression. + + + +read all files referenced by the invoking prompt's execution_context before starting. + + + + + +read project state to determine current position: + +```bash +# Get state snapshot +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" state json 2>/dev/null || echo "{}" +``` + +Also read: +- `.planning/STATE.md` — current phase, progress, plan counts +- `.planning/ROADMAP.md` — milestone structure and phase list + +Extract: +- `current_phase` — which phase is active +- `plan_of` / `plans_total` — plan execution progress +- `progress` — overall percentage +- `status` — active, paused, etc. + +If no `.planning/` directory exists: +``` +No GSD project detected. Run `/gsd-new-project` to get started. +``` +Exit. + + + +Apply routing rules based on state: + +**Route 1: No phases exist yet → discuss** +If ROADMAP has phases but no phase directories exist on disk: +→ Next action: `/gsd-discuss-phase ` + +**Route 2: Phase exists but has no CONTEXT.md or RESEARCH.md → discuss** +If the current phase directory exists but has neither CONTEXT.md nor RESEARCH.md: +→ Next action: `/gsd-discuss-phase ` + +**Route 3: Phase has context but no plans → plan** +If the current phase has CONTEXT.md (or RESEARCH.md) but no PLAN.md files: +→ Next action: `/gsd-plan-phase ` + +**Route 4: Phase has plans but incomplete summaries → execute** +If plans exist but not all have matching summaries: +→ Next action: `/gsd-execute-phase ` + +**Route 5: All plans have summaries → verify and complete** +If all plans in the current phase have summaries: +→ Next action: `/gsd-verify-work` then `/gsd-complete-phase` + +**Route 6: Phase complete, next phase exists → advance** +If the current phase is complete and the next phase exists in ROADMAP: +→ Next action: `/gsd-discuss-phase ` + +**Route 7: All phases complete → complete milestone** +If all phases are complete: +→ Next action: `/gsd-complete-milestone` + +**Route 8: Paused → resume** +If STATE.md shows paused_at: +→ Next action: `/gsd-resume-work` + + + +Display the determination: + +``` +## GSD Next + +**Current:** Phase [N] — [name] | [progress]% +**Status:** [status description] + +▶ **Next step:** `/gsd-[command] [args]` + [One-line explanation of why this is the next step] +``` + +Then immediately invoke the determined command via command. +Do not ask for confirmation — the whole point of `/gsd-next` is zero-friction advancement. + + + + + +- [ ] Project state correctly detected +- [ ] Next action correctly determined from routing rules +- [ ] Command invoked immediately without user confirmation +- [ ] Clear status shown before invoking + diff --git a/gsd-opencode/get-shit-done/workflows/node-repair.md b/gsd-opencode/get-shit-done/workflows/node-repair.md new file mode 100644 index 0000000..d833fe4 --- /dev/null +++ b/gsd-opencode/get-shit-done/workflows/node-repair.md @@ -0,0 +1,92 @@ + +Autonomous repair operator for failed task verification. Invoked by execute-plan when a task fails its done-criteria. Proposes and attempts structured fixes before escalating to the user. + + + +- FAILED_TASK: task number, name, and done-criteria from the plan +- ERROR: What verification produced — actual result vs expected +- PLAN_CONTEXT: Adjacent tasks and phase goal (for constraint awareness) +- REPAIR_BUDGET: Max repair attempts remaining (default: 2) + + + +Analyze the failure and choose exactly one repair strategy: + +**RETRY** — The approach was right but execution failed. Try again with a concrete adjustment. +- Use when: command error, missing dependency, wrong path, env issue, transient failure +- Output: `RETRY: [specific adjustment to make before retrying]` + +**DECOMPOSE** — The task is too coarse. Break it into smaller verifiable sub-steps. +- Use when: done-criteria covers multiple concerns, implementation gaps are structural +- Output: `DECOMPOSE: [sub-task 1] | [sub-task 2] | ...` (max 3 sub-tasks) +- Sub-tasks must each have a single verifiable outcome + +**PRUNE** — The task is infeasible given current constraints. Skip with justification. +- Use when: prerequisite missing and not fixable here, out of scope, contradicts an earlier decision +- Output: `PRUNE: [one-sentence justification]` + +**ESCALATE** — Repair budget exhausted, or this is an architectural decision (Rule 4). +- Use when: RETRY failed more than once with different approaches, or fix requires structural change +- Output: `ESCALATE: [what was tried] | [what decision is needed]` + + + + + +read the error and done-criteria carefully. Ask: +1. Is this a transient/environmental issue? → RETRY +2. Is the task verifiably too broad? → DECOMPOSE +3. Is a prerequisite genuinely missing and unfixable in scope? → PRUNE +4. Has RETRY already been attempted with this task? Check REPAIR_BUDGET. If 0 → ESCALATE + + + +If RETRY: +1. Apply the specific adjustment stated in the directive +2. Re-run the task implementation +3. Re-run verification +4. If passes → continue normally, log `[Node Repair - RETRY] task [X]: [adjustment made]` +5. If fails again → decrement REPAIR_BUDGET, re-invoke node-repair with updated context + + + +If DECOMPOSE: +1. Replace the failed task inline with the sub-tasks (do not modify PLAN.md on disk) +2. Execute sub-tasks sequentially, each with its own verification +3. If all sub-tasks pass → treat original task as succeeded, log `[Node Repair - DECOMPOSE] task [X] → [N] sub-tasks` +4. If a sub-task fails → re-invoke node-repair for that sub-task (REPAIR_BUDGET applies per sub-task) + + + +If PRUNE: +1. Mark task as skipped with justification +2. Log to SUMMARY "Issues Encountered": `[Node Repair - PRUNE] task [X]: [justification]` +3. Continue to next task + + + +If ESCALATE: +1. Surface to user via verification_failure_gate with full repair history +2. Present: what was tried (each RETRY/DECOMPOSE attempt), what the blocker is, options available +3. Wait for user direction before continuing + + + + + +All repair actions must appear in SUMMARY.md under "## Deviations from Plan": + +| Type | Format | +|------|--------| +| RETRY success | `[Node Repair - RETRY] task X: [adjustment] — resolved` | +| RETRY fail → ESCALATE | `[Node Repair - RETRY] task X: [N] attempts exhausted — escalated to user` | +| DECOMPOSE | `[Node Repair - DECOMPOSE] task X split into [N] sub-tasks — all passed` | +| PRUNE | `[Node Repair - PRUNE] task X skipped: [justification]` | + + + +- REPAIR_BUDGET defaults to 2 per task. Configurable via config.json `workflow.node_repair_budget`. +- Never modify PLAN.md on disk — decomposed sub-tasks are in-memory only. +- DECOMPOSE sub-tasks must be more specific than the original, not synonymous rewrites. +- If config.json `workflow.node_repair` is `false`, skip directly to verification_failure_gate (user retains original behavior). + diff --git a/gsd-opencode/get-shit-done/workflows/note.md b/gsd-opencode/get-shit-done/workflows/note.md new file mode 100644 index 0000000..89c2878 --- /dev/null +++ b/gsd-opencode/get-shit-done/workflows/note.md @@ -0,0 +1,156 @@ + +Zero-friction idea capture. One write call, one confirmation line. No questions, no prompts. +Runs inline — no task, no question, no bash. + + + +read all files referenced by the invoking prompt's execution_context before starting. + + + + + +**Note storage format.** + +Notes are stored as individual markdown files: + +- **Project scope**: `.planning/notes/{YYYY-MM-DD}-{slug}.md` — used when `.planning/` exists in cwd +- **Global scope**: `$HOME/.config/opencode/notes/{YYYY-MM-DD}-{slug}.md` — fallback when no `.planning/`, or when `--global` flag is present + +Each note file: + +```markdown +--- +date: "YYYY-MM-DD HH:mm" +promoted: false +--- + +{note text verbatim} +``` + +**`--global` flag**: Strip `--global` from anywhere in `$ARGUMENTS` before parsing. When present, force global scope regardless of whether `.planning/` exists. + +**Important**: Do NOT create `.planning/` if it doesn't exist. Fall back to global scope silently. + + + +**Parse subcommand from $ARGUMENTS (after stripping --global).** + +| Condition | Subcommand | +|-----------|------------| +| Arguments are exactly `list` (case-insensitive) | **list** | +| Arguments are exactly `promote ` where N is a number | **promote** | +| Arguments are empty (no text at all) | **list** | +| Anything else | **append** (the text IS the note) | + +**Critical**: `list` is only a subcommand when it's the ENTIRE argument. `/gsd-note list of groceries` saves a note with text "list of groceries". Same for `promote` — only a subcommand when followed by exactly one number. + + + +**Subcommand: append — create a timestamped note file.** + +1. Determine scope (project or global) per storage format above +2. Ensure the notes directory exists (`.planning/notes/` or `$HOME/.config/opencode/notes/`) +3. Generate slug: first ~4 meaningful words of the note text, lowercase, hyphen-separated (strip articles/prepositions from the start) +4. Generate filename: `{YYYY-MM-DD}-{slug}.md` + - If a file with that name already exists, append `-2`, `-3`, etc. +5. write the file with frontmatter and note text (see storage format) +6. Confirm with exactly one line: `Noted ({scope}): {note text}` + - Where `{scope}` is "project" or "global" + +**Constraints:** +- **Never modify the note text** — capture verbatim, including typos +- **Never ask questions** — just write and confirm +- **Timestamp format**: Use local time, `YYYY-MM-DD HH:mm` (24-hour, no seconds) + + + +**Subcommand: list — show notes from both scopes.** + +1. glob `.planning/notes/*.md` (if directory exists) — project notes +2. glob `$HOME/.config/opencode/notes/*.md` (if directory exists) — global notes +3. For each file, read frontmatter to get `date` and `promoted` status +4. Exclude files where `promoted: true` from active counts (but still show them, dimmed) +5. Sort by date, number all active entries sequentially starting at 1 +6. If total active entries > 20, show only the last 10 with a note about how many were omitted + +**Display format:** + +``` +Notes: + +Project (.planning/notes/): + 1. [2026-02-08 14:32] refactor the hook system to support async validators + 2. [promoted] [2026-02-08 14:40] add rate limiting to the API endpoints + 3. [2026-02-08 15:10] consider adding a --dry-run flag to build + +Global ($HOME/.config/opencode/notes/): + 4. [2026-02-08 10:00] cross-project idea about shared config + +{count} active note(s). Use `/gsd-note promote ` to convert to a todo. +``` + +If a scope has no directory or no entries, show: `(no notes)` + + + +**Subcommand: promote — convert a note into a todo.** + +1. Run the **list** logic to build the numbered index (both scopes) +2. Find entry N from the numbered list +3. If N is invalid or refers to an already-promoted note, tell the user and stop +4. **Requires `.planning/` directory** — if it doesn't exist, warn: "Todos require a GSD project. Run `/gsd-new-project` to initialize one." +5. Ensure `.planning/todos/pending/` directory exists +6. Generate todo ID: `{NNN}-{slug}` where NNN is the next sequential number (scan both `.planning/todos/pending/` and `.planning/todos/done/` for the highest existing number, increment by 1, zero-pad to 3 digits) and slug is the first ~4 meaningful words of the note text +7. Extract the note text from the source file (body after frontmatter) +8. Create `.planning/todos/pending/{id}.md`: + +```yaml +--- +title: "{note text}" +status: pending +priority: P2 +source: "promoted from /gsd-note" +created: {YYYY-MM-DD} +theme: general +--- + +## Goal + +{note text} + +## Context + +Promoted from quick note captured on {original date}. + +## Acceptance Criteria + +- [ ] {primary criterion derived from note text} +``` + +9. Mark the source note file as promoted: update its frontmatter to `promoted: true` +10. Confirm: `Promoted note {N} to todo {id}: {note text}` + + + + + +1. **"list" as note text**: `/gsd-note list of things` saves note "list of things" (subcommand only when `list` is the entire arg) +2. **No `.planning/`**: Falls back to global `$HOME/.config/opencode/notes/` — works in any directory +3. **Promote without project**: Warns that todos require `.planning/`, suggests `/gsd-new-project` +4. **Large files**: `list` shows last 10 when >20 active entries +5. **Duplicate slugs**: Append `-2`, `-3` etc. to filename if slug already used on same date +6. **`--global` position**: Stripped from anywhere — `--global my idea` and `my idea --global` both save "my idea" globally +7. **Promote already-promoted**: Tell user "Note {N} is already promoted" and stop +8. **Empty note text after stripping flags**: Treat as `list` subcommand + + + +- [ ] Append: Note file written with correct frontmatter and verbatim text +- [ ] Append: No questions asked — instant capture +- [ ] List: Both scopes shown with sequential numbering +- [ ] List: Promoted notes shown but dimmed +- [ ] Promote: Todo created with correct format +- [ ] Promote: Source note marked as promoted +- [ ] Global fallback: Works when no `.planning/` exists + diff --git a/gsd-opencode/get-shit-done/workflows/pause-work.md b/gsd-opencode/get-shit-done/workflows/pause-work.md index 611c335..8cfc52e 100644 --- a/gsd-opencode/get-shit-done/workflows/pause-work.md +++ b/gsd-opencode/get-shit-done/workflows/pause-work.md @@ -1,6 +1,6 @@ - -Create `.continue-here.md` handoff file to preserve complete work state across sessions. Enables seamless resumption with full context restoration. - + +Create structured `.planning/HANDOFF.json` and `.continue-here.md` handoff files to preserve complete work state across sessions. The JSON provides machine-readable state for `/gsd-resume-work`; the markdown provides human-readable context. + read all files referenced by the invoking prompt's execution_context before starting. @@ -13,7 +13,7 @@ Find current phase directory from most recently modified files: ```bash # Find most recent phase directory with work -ls -lt .planning/phases/*/PLAN.md 2>/dev/null | head -1 | grep -oP 'phases/\K[^/]+' +(ls -lt .planning/phases/*/PLAN.md 2>/dev/null || true) | head -1 | grep -oP 'phases/\K[^/]+' || true ``` If no active phase detected, ask user which phase they're pausing work on. @@ -27,10 +27,61 @@ If no active phase detected, ask user which phase they're pausing work on. 3. **Work remaining**: What's left in current plan/phase 4. **Decisions made**: Key decisions and rationale 5. **Blockers/issues**: Anything stuck -6. **Mental context**: The approach, next steps, "vibe" -7. **Files modified**: What's changed but not committed +6. **Human actions pending**: Things that need manual intervention (MCP setup, API keys, approvals, manual testing) +7. **Background processes**: Any running servers/watchers that were part of the workflow +8. **Files modified**: What's changed but not committed Ask user for clarifications if needed via conversational questions. + +**Also inspect SUMMARY.md files for false completions:** +```bash +# Check for placeholder content in existing summaries +grep -l "To be filled\|placeholder\|TBD" .planning/phases/*/*.md 2>/dev/null || true +``` +Report any summaries with placeholder content as incomplete items. + + + +**write structured handoff to `.planning/HANDOFF.json`:** + +```bash +timestamp=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" current-timestamp full --raw) +``` + +```json +{ + "version": "1.0", + "timestamp": "{timestamp}", + "phase": "{phase_number}", + "phase_name": "{phase_name}", + "phase_dir": "{phase_dir}", + "plan": {current_plan_number}, + "task": {current_task_number}, + "total_tasks": {total_task_count}, + "status": "paused", + "completed_tasks": [ + {"id": 1, "name": "{task_name}", "status": "done", "commit": "{short_hash}"}, + {"id": 2, "name": "{task_name}", "status": "done", "commit": "{short_hash}"}, + {"id": 3, "name": "{task_name}", "status": "in_progress", "progress": "{what_done}"} + ], + "remaining_tasks": [ + {"id": 4, "name": "{task_name}", "status": "not_started"}, + {"id": 5, "name": "{task_name}", "status": "not_started"} + ], + "blockers": [ + {"description": "{blocker}", "type": "technical|human_action|external", "workaround": "{if any}"} + ], + "human_actions_pending": [ + {"action": "{what needs to be done}", "context": "{why}", "blocking": true} + ], + "decisions": [ + {"decision": "{what}", "rationale": "{why}", "phase": "{phase_number}"} + ], + "uncommitted_files": [], + "next_action": "{specific first action when resuming}", + "context_notes": "{mental state, approach, what you were thinking}" +} +``` @@ -92,19 +143,22 @@ timestamp=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" curren ```bash -node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/phases/*/.continue-here.md +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/phases/*/.continue-here.md .planning/HANDOFF.json ``` ``` -✓ Handoff created: .planning/phases/[XX-name]/.continue-here.md +✓ Handoff created: + - .planning/HANDOFF.json (structured, machine-readable) + - .planning/phases/[XX-name]/.continue-here.md (human-readable) Current state: - Phase: [XX-name] - task: [X] of [Y] - Status: [in_progress/blocked] +- Blockers: [count] ({human_actions_pending count} need human action) - Committed as WIP To resume: /gsd-resume-work diff --git a/gsd-opencode/get-shit-done/workflows/plan-milestone-gaps.md b/gsd-opencode/get-shit-done/workflows/plan-milestone-gaps.md index e17139c..5288ce0 100644 --- a/gsd-opencode/get-shit-done/workflows/plan-milestone-gaps.md +++ b/gsd-opencode/get-shit-done/workflows/plan-milestone-gaps.md @@ -1,6 +1,6 @@ - + Create all phases necessary to close gaps identified by `/gsd-audit-milestone`. Reads MILESTONE-AUDIT.md, groups gaps into logical phases, creates phase entries in ROADMAP.md, and offers to plan each phase. One command creates all fix phases — no manual `/gsd-add-phase` per gap. - + read all files referenced by the invoking prompt's execution_context before starting. @@ -12,7 +12,7 @@ read all files referenced by the invoking prompt's execution_context before star ```bash # Find the most recent audit file -ls -t .planning/v*-MILESTONE-AUDIT.md 2>/dev/null | head -1 +(ls -t .planning/v*-MILESTONE-AUDIT.md 2>/dev/null || true) | head -1 ``` Parse YAML frontmatter to extract structured gaps: @@ -65,8 +65,7 @@ Gap: Flow "View dashboard" broken at data fetch Find highest existing phase: ```bash # Get sorted phase list, extract last one -PHASES=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" phases list) -HIGHEST=$(printf '%s\n' "$PHASES" | jq -r '.directories[-1]') +HIGHEST=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" phases list --pick directories[-1]) ``` New phases continue from there: diff --git a/gsd-opencode/get-shit-done/workflows/plan-phase.md b/gsd-opencode/get-shit-done/workflows/plan-phase.md index 87f6ce4..bd7f962 100644 --- a/gsd-opencode/get-shit-done/workflows/plan-phase.md +++ b/gsd-opencode/get-shit-done/workflows/plan-phase.md @@ -1,6 +1,6 @@ - + Create executable phase prompts (PLAN.md files) for a roadmap phase with integrated research and verification. Default flow: Research (if needed) -> Plan -> Verify -> Done. Orchestrates gsd-phase-researcher, gsd-planner, and gsd-plan-checker agents with a revision loop (max 3 iterations). - + read all files referenced by the invoking prompt's execution_context before starting. @@ -8,6 +8,13 @@ read all files referenced by the invoking prompt's execution_context before star @$HOME/.config/opencode/get-shit-done/references/ui-brand.md + +Valid GSD subagent types (use exact names — do not fall back to 'general'): +- gsd-phase-researcher — Researches technical approaches for a phase +- gsd-planner — Creates detailed plans from phase scope +- gsd-plan-checker — Reviews plan quality before execution + + ## 1. Initialize @@ -17,17 +24,22 @@ Load all context in one call (paths only to minimize orchestrator context): ```bash INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init plan-phase "$PHASE") if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +AGENT_SKILLS_RESEARCHER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-researcher 2>/dev/null) +AGENT_SKILLS_PLANNER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-planner 2>/dev/null) +AGENT_SKILLS_CHECKER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-checker 2>/dev/null) ``` -Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_enabled`, `plan_checker_enabled`, `nyquist_validation_enabled`, `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `plan_count`, `planning_exists`, `roadmap_exists`, `phase_req_ids`. +Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_enabled`, `plan_checker_enabled`, `nyquist_validation_enabled`, `commit_docs`, `text_mode`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_reviews`, `has_plans`, `plan_count`, `planning_exists`, `roadmap_exists`, `phase_req_ids`. -**File paths (for blocks):** `state_path`, `roadmap_path`, `requirements_path`, `context_path`, `research_path`, `verification_path`, `uat_path`. These are null if files don't exist. +**File paths (for blocks):** `state_path`, `roadmap_path`, `requirements_path`, `context_path`, `research_path`, `verification_path`, `uat_path`, `reviews_path`. These are null if files don't exist. **If `planning_exists` is false:** Error — run `/gsd-new-project` first. ## 2. Parse and Normalize Arguments -Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--gaps`, `--skip-verify`, `--prd `). +Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--gaps`, `--skip-verify`, `--prd `, `--reviews`, `--text`). + +Set `TEXT_MODE=true` if `--text` is present in $ARGUMENTS OR `text_mode` from init JSON is `true`. When `TEXT_MODE` is active, replace every `question` call with a plain-text numbered list and ask the user to type their choice number. This is required for OpenCode remote sessions (`/rc` mode) where TUI menus don't work through the OpenCode App. Extract `--prd ` from $ARGUMENTS. If present, set PRD_FILE to the filepath. @@ -40,6 +52,24 @@ mkdir -p ".planning/phases/${padded_phase}-${phase_slug}" **Existing artifacts from init:** `has_research`, `has_plans`, `plan_count`. +## 2.5. Validate `--reviews` Prerequisite + +**Skip if:** No `--reviews` flag. + +**If `--reviews` AND `--gaps`:** Error — cannot combine `--reviews` with `--gaps`. These are conflicting modes. + +**If `--reviews` AND `has_reviews` is false (no REVIEWS.md in phase dir):** + +Error: +``` +No REVIEWS.md found for Phase {N}. Run reviews first: + +/gsd-review --phase {N} + +Then re-run /gsd-plan-phase {N} --reviews +``` +Exit workflow. + ## 3. Validate Phase ```bash @@ -77,6 +107,7 @@ Generating CONTEXT.md from requirements... - Extract all requirements, user stories, acceptance criteria, and constraints from the PRD - Map each to a locked decision (everything in the PRD is treated as a locked decision) - Identify any areas the PRD doesn't cover and mark as "OpenCode's Discretion" + - **Extract canonical refs** from ROADMAP.md for this phase, plus any specs/ADRs referenced in the PRD — expand to full file paths (MANDATORY) - Create CONTEXT.md in the phase directory 4. write CONTEXT.md: @@ -106,6 +137,21 @@ Generating CONTEXT.md from requirements... + +## Canonical References + +**Downstream agents MUST read these before planning or implementing.** + +[MANDATORY. Extract from ROADMAP.md and any docs referenced in the PRD. +Use full relative paths. Group by topic area.] + +### [Topic area] +- `path/to/spec-or-adr.md` — [What it decides/defines] + +[If no external specs: "No external specs — requirements fully captured in decisions above"] + + + ## Specific Ideas @@ -146,24 +192,86 @@ If `context_path` is not null, display: `Using phase context from: ${context_pat **If `context_path` is null (no CONTEXT.md exists):** -Use question: +read discuss mode for context gate label: +```bash +DISCUSS_MODE=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.discuss_mode 2>/dev/null || echo "discuss") +``` + +If `TEXT_MODE` is true, present as a plain-text numbered list: +``` +No CONTEXT.md found for Phase {X}. Plans will use research and requirements only — your design preferences won't be included. + +1. Continue without context — Plan using research + requirements only +[If DISCUSS_MODE is "assumptions":] +2. Gather context (assumptions mode) — Analyze codebase and surface assumptions before planning +[If DISCUSS_MODE is "discuss" or unset:] +2. Run discuss-phase first — Capture design decisions before planning + +Enter number: +``` + +Otherwise use question: - header: "No context" - question: "No CONTEXT.md found for Phase {X}. Plans will use research and requirements only — your design preferences won't be included. Continue or capture context first?" - options: - "Continue without context" — Plan using research + requirements only + If `DISCUSS_MODE` is `"assumptions"`: + - "Gather context (assumptions mode)" — Analyze codebase and surface assumptions before planning + If `DISCUSS_MODE` is `"discuss"` (or unset): - "Run discuss-phase first" — Capture design decisions before planning If "Continue without context": Proceed to step 5. -If "Run discuss-phase first": Display `/gsd-discuss-phase {X}` and exit workflow. +If "Run discuss-phase first": + **IMPORTANT:** Do NOT invoke discuss-phase as a nested skill/task call — question + does not work correctly in nested subcontexts (#1009). Instead, display the command + and exit so the user runs it as a top-level command: + ``` + Run this command first, then re-run /gsd-plan-phase {X} ${GSD_WS}: + + /gsd-discuss-phase {X} ${GSD_WS} + ``` + **Exit the plan-phase workflow. Do not continue.** ## 5. Handle Research -**Skip if:** `--gaps` flag, `--skip-research` flag, or `research_enabled` is false (from init) without `--research` override. +**Skip if:** `--gaps` flag or `--skip-research` flag or `--reviews` flag. **If `has_research` is true (from init) AND no `--research` flag:** Use existing, skip to step 6. **If RESEARCH.md missing OR `--research` flag:** +**If no explicit flag (`--research` or `--skip-research`) and not `--auto`:** +Ask the user whether to research, with a contextual recommendation based on the phase: + +If `TEXT_MODE` is true, present as a plain-text numbered list: +``` +Research before planning Phase {X}: {phase_name}? + +1. Research first (Recommended) — Investigate domain, patterns, and dependencies before planning. Best for new features, unfamiliar integrations, or architectural changes. +2. Skip research — Plan directly from context and requirements. Best for bug fixes, simple refactors, or well-understood tasks. + +Enter number: +``` + +Otherwise use question: +``` +question([ + { + question: "Research before planning Phase {X}: {phase_name}?", + header: "Research", + multiSelect: false, + options: [ + { label: "Research first (Recommended)", description: "Investigate domain, patterns, and dependencies before planning. Best for new features, unfamiliar integrations, or architectural changes." }, + { label: "Skip research", description: "Plan directly from context and requirements. Best for bug fixes, simple refactors, or well-understood tasks." } + ] + } +]) +``` + +If user selects "Skip research": skip to step 6. + +**If `--auto` and `research_enabled` is false:** Skip research silently (preserves automated behavior). + Display banner: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ @@ -176,7 +284,7 @@ Display banner: ### Spawn gsd-phase-researcher ```bash -PHASE_DESC=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "${PHASE}" | jq -r '.section') +PHASE_DESC=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "${PHASE}" --pick section) ``` Research prompt: @@ -193,6 +301,8 @@ Answer: "What do I need to know to PLAN this phase well?" - {state_path} (Project decisions and history) +${AGENT_SKILLS_RESEARCHER} + **Phase description:** {phase_description} **Phase requirement IDs (MUST address):** {phase_req_ids} @@ -222,10 +332,19 @@ task( ## 5.5. Create Validation Strategy -MANDATORY unless `nyquist_validation_enabled` is false. +Skip if `nyquist_validation_enabled` is false OR `research_enabled` is false. + +If `research_enabled` is false and `nyquist_validation_enabled` is true: warn "Nyquist validation enabled but research disabled — VALIDATION.md cannot be created without RESEARCH.md. Plans will lack validation requirements (Dimension 8)." Continue to step 6. + +**But Nyquist is not applicable for this run** when all of the following are true: +- `research_enabled` is false +- `has_research` is false +- no `--research` flag was provided + +In that case: **skip validation-strategy creation entirely**. Do **not** expect `RESEARCH.md` or `VALIDATION.md` for this run, and continue to Step 6. ```bash -grep -l "## Validation Architecture" "${PHASE_DIR}"/*-RESEARCH.md 2>/dev/null +grep -l "## Validation Architecture" "${PHASE_DIR}"/*-RESEARCH.md 2>/dev/null || true ``` **If found:** @@ -237,43 +356,106 @@ grep -l "## Validation Architecture" "${PHASE_DIR}"/*-RESEARCH.md 2>/dev/null test -f "${PHASE_DIR}/${PADDED_PHASE}-VALIDATION.md" && echo "VALIDATION_CREATED=true" || echo "VALIDATION_CREATED=false" ``` 5. If `VALIDATION_CREATED=false`: STOP — do not proceed to Step 6 -6. If `commit_docs`: `commit-docs "docs(phase-${PHASE}): add validation strategy"` +6. If `commit_docs`: `commit "docs(phase-${PHASE}): add validation strategy"` **If not found:** Warn and continue — plans may fail Dimension 8. +## 5.6. UI Design Contract Gate + +> Skip if `workflow.ui_phase` is explicitly `false` AND `workflow.ui_safety_gate` is explicitly `false` in `.planning/config.json`. If keys are absent, treat as enabled. + +```bash +UI_PHASE_CFG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.ui_phase 2>/dev/null || echo "true") +UI_GATE_CFG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.ui_safety_gate 2>/dev/null || echo "true") +``` + +**If both are `false`:** Skip to step 6. + +Check if phase has frontend indicators: + +```bash +PHASE_SECTION=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "${PHASE}" 2>/dev/null) +echo "$PHASE_SECTION" | grep -iE "UI|interface|frontend|component|layout|page|screen|view|form|dashboard|widget" > /dev/null 2>&1 +HAS_UI=$? +``` + +**If `HAS_UI` is 0 (frontend indicators found):** + +Check for existing UI-SPEC: +```bash +UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1) +``` + +**If UI-SPEC.md found:** Set `UI_SPEC_PATH=$UI_SPEC_FILE`. Display: `Using UI design contract: ${UI_SPEC_PATH}` + +**If UI-SPEC.md missing AND `UI_GATE_CFG` is `true`:** + +If `TEXT_MODE` is true, present as a plain-text numbered list: +``` +Phase {N} has frontend indicators but no UI-SPEC.md. Generate a design contract before planning? + +1. Generate UI-SPEC first — Run /gsd-ui-phase {N} then re-run /gsd-plan-phase {N} +2. Continue without UI-SPEC +3. Not a frontend phase + +Enter number: +``` + +Otherwise use question: +- header: "UI Design Contract" +- question: "Phase {N} has frontend indicators but no UI-SPEC.md. Generate a design contract before planning?" +- options: + - "Generate UI-SPEC first" → Display: "Run `/gsd-ui-phase {N} ${GSD_WS}` then re-run `/gsd-plan-phase {N} ${GSD_WS}`". Exit workflow. + - "Continue without UI-SPEC" → Continue to step 6. + - "Not a frontend phase" → Continue to step 6. + +**If `HAS_UI` is 1 (no frontend indicators):** Skip silently to step 6. + ## 6. Check Existing Plans ```bash -ls "${PHASE_DIR}"/*-PLAN.md 2>/dev/null +ls "${PHASE_DIR}"/*-PLAN.md 2>/dev/null || true ``` -**If exists:** Offer: 1) Add more plans, 2) View existing, 3) Replan from scratch. +**If exists AND `--reviews` flag:** Skip prompt — go straight to replanning (the purpose of `--reviews` is to replan with review feedback). + +**If exists AND no `--reviews` flag:** Offer: 1) Add more plans, 2) View existing, 3) Replan from scratch. ## 7. Use Context Paths from INIT Extract from INIT JSON: ```bash -STATE_PATH=$(printf '%s\n' "$INIT" | jq -r '.state_path // empty') -ROADMAP_PATH=$(printf '%s\n' "$INIT" | jq -r '.roadmap_path // empty') -REQUIREMENTS_PATH=$(printf '%s\n' "$INIT" | jq -r '.requirements_path // empty') -RESEARCH_PATH=$(printf '%s\n' "$INIT" | jq -r '.research_path // empty') -VERIFICATION_PATH=$(printf '%s\n' "$INIT" | jq -r '.verification_path // empty') -UAT_PATH=$(printf '%s\n' "$INIT" | jq -r '.uat_path // empty') -CONTEXT_PATH=$(printf '%s\n' "$INIT" | jq -r '.context_path // empty') +_gsd_field() { node -e "const o=JSON.parse(process.argv[1]); const v=o[process.argv[2]]; process.stdout.write(v==null?'':String(v))" "$1" "$2"; } +STATE_PATH=$(_gsd_field "$INIT" state_path) +ROADMAP_PATH=$(_gsd_field "$INIT" roadmap_path) +REQUIREMENTS_PATH=$(_gsd_field "$INIT" requirements_path) +RESEARCH_PATH=$(_gsd_field "$INIT" research_path) +VERIFICATION_PATH=$(_gsd_field "$INIT" verification_path) +UAT_PATH=$(_gsd_field "$INIT" uat_path) +CONTEXT_PATH=$(_gsd_field "$INIT" context_path) +REVIEWS_PATH=$(_gsd_field "$INIT" reviews_path) ``` ## 7.5. Verify Nyquist Artifacts -Skip if `nyquist_validation_enabled` is false. +Skip if `nyquist_validation_enabled` is false OR `research_enabled` is false. + +Also skip if all of the following are true: +- `research_enabled` is false +- `has_research` is false +- no `--research` flag was provided + +In that no-research path, Nyquist artifacts are **not required** for this run. ```bash VALIDATION_EXISTS=$(ls "${PHASE_DIR}"/*-VALIDATION.md 2>/dev/null | head -1) ``` -If missing and Nyquist enabled — ask user: -1. Re-run: `/gsd-plan-phase {PHASE} --research` -2. Disable Nyquist in config +If missing and Nyquist is still enabled/applicable — ask user: +1. Re-run: `/gsd-plan-phase {PHASE} --research ${GSD_WS}` +2. Disable Nyquist with the exact command: + `node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-set workflow.nyquist_validation false` 3. Continue anyway (plans fail Dimension 8) Proceed to Step 8 only if user selects 2 or 3. @@ -294,7 +476,7 @@ Planner prompt: ```markdown **Phase:** {phase_number} -**Mode:** {standard | gap_closure} +**Mode:** {standard | gap_closure | reviews} - {state_path} (Project State) @@ -304,8 +486,12 @@ Planner prompt: - {research_path} (Technical Research) - {verification_path} (Verification Gaps - if --gaps) - {uat_path} (UAT Gaps - if --gaps) +- {reviews_path} (Cross-AI Review Feedback - if --reviews) +- {UI_SPEC_PATH} (UI Design Contract — visual/interaction specs, if exists) +${AGENT_SKILLS_PLANNER} + **Phase requirement IDs (every ID MUST appear in a plan's `requirements` field):** {phase_req_ids} **Project instructions:** read ./AGENTS.md if exists — follow project-specific guidelines @@ -315,15 +501,47 @@ Planner prompt: Output consumed by /gsd-execute-phase. Plans need: - Frontmatter (wave, depends_on, files_modified, autonomous) -- Tasks in XML format +- Tasks in XML format with read_first and acceptance_criteria fields (MANDATORY on every task) - Verification criteria - must_haves for goal-backward verification + +## Anti-Shallow Execution Rules (MANDATORY) + +Every task MUST include these fields — they are NOT optional: + +1. **``** — Files the executor MUST read before touching anything. Always include: + - The file being modified (so executor sees current state, not assumptions) + - Any "source of truth" file referenced in CONTEXT.md (reference implementations, existing patterns, config files, schemas) + - Any file whose patterns, signatures, types, or conventions must be replicated or respected + +2. **``** — Verifiable conditions that prove the task was done correctly. Rules: + - Every criterion must be checkable with grep, file read, test command, or CLI output + - NEVER use subjective language ("looks correct", "properly configured", "consistent with") + - ALWAYS include exact strings, patterns, values, or command outputs that must be present + - Examples: + - Code: `auth.py contains def verify_token(` / `test_auth.py exits 0` + - Config: `.env.example contains DATABASE_URL=` / `Dockerfile contains HEALTHCHECK` + - Docs: `README.md contains '## Installation'` / `API.md lists all endpoints` + - Infra: `deploy.yml has rollback step` / `docker-compose.yml has healthcheck for db` + +3. **``** — Must include CONCRETE values, not references. Rules: + - NEVER say "align X with Y", "match X to Y", "update to be consistent" without specifying the exact target state + - ALWAYS include the actual values: config keys, function signatures, SQL statements, class names, import paths, env vars, etc. + - If CONTEXT.md has a comparison table or expected values, copy them into the action verbatim + - The executor should be able to complete the task from the action text alone, without needing to read CONTEXT.md or reference files (read_first is for verification, not discovery) + +**Why this matters:** Executor agents work from the plan text. Vague instructions like "update the config to match production" produce shallow one-line changes. Concrete instructions like "add DATABASE_URL=postgresql://... , set POOL_SIZE=20, add REDIS_URL=redis://..." produce complete work. The cost of verbose plans is far less than the cost of re-doing shallow execution. + + - [ ] PLAN.md files created in phase directory - [ ] Each plan has valid frontmatter - [ ] Tasks are specific and actionable +- [ ] Every task has `` with at least the file being modified +- [ ] Every task has `` with grep-verifiable conditions +- [ ] Every `` contains concrete values (no "align X with Y" without specifying what) - [ ] Dependencies correctly identified - [ ] Waves assigned for parallel execution - [ ] must_haves derived from phase goal @@ -371,6 +589,8 @@ Checker prompt: - {research_path} (Technical Research — includes Validation Architecture) +${AGENT_SKILLS_CHECKER} + **Phase requirement IDs (MUST ALL be covered):** {phase_req_ids} **Project instructions:** read ./AGENTS.md if exists — verify plans honor project guidelines @@ -417,6 +637,8 @@ Revision prompt: - {context_path} (USER DECISIONS from /gsd-discuss-phase) +${AGENT_SKILLS_PLANNER} + **Checker issues:** {structured_issues_from_checker} @@ -444,11 +666,62 @@ Display: `Max iterations reached. {N} issues remain:` + issue list Offer: 1) Force proceed, 2) Provide guidance and retry, 3) Abandon -## 13. Present Final Status +## 13. Requirements Coverage Gate + +After plans pass the checker (or checker is skipped), verify that all phase requirements are covered by at least one plan. + +**Skip if:** `phase_req_ids` is null or TBD (no requirements mapped to this phase). + +**Step 1: Extract requirement IDs claimed by plans** +```bash +# Collect all requirement IDs from plan frontmatter +PLAN_REQS=$(grep -h "requirements_addressed\|requirements:" ${PHASE_DIR}/*-PLAN.md 2>/dev/null | tr -d '[]' | tr ',' '\n' | sed 's/^[[:space:]]*//' | sort -u) +``` + +**Step 2: Compare against phase requirements from ROADMAP** + +For each REQ-ID in `phase_req_ids`: +- If REQ-ID appears in `PLAN_REQS` → covered ✓ +- If REQ-ID does NOT appear in any plan → uncovered ✗ + +**Step 3: Check CONTEXT.md features against plan objectives** + +read CONTEXT.md `` section. Extract feature/capability names. Check each against plan `` blocks. Features not mentioned in any plan objective → potentially dropped. + +**Step 4: Report** + +If all requirements covered and no dropped features: +``` +✓ Requirements coverage: {N}/{N} REQ-IDs covered by plans +``` +→ Proceed to step 14. + +If gaps found: +``` +## ⚠ Requirements Coverage Gap + +{M} of {N} phase requirements are not assigned to any plan: + +| REQ-ID | Description | Plans | +|--------|-------------|-------| +| {id} | {from REQUIREMENTS.md} | None | + +{K} CONTEXT.md features not found in plan objectives: +- {feature_name} — described in CONTEXT.md but no plan covers it + +Options: +1. Re-plan to include missing requirements (recommended) +2. Move uncovered requirements to next phase +3. Proceed anyway — accept coverage gaps +``` + +If `TEXT_MODE` is true, present as a plain-text numbered list (options already shown in the block above). Otherwise use question to present the options. + +## 14. Present Final Status Route to `` OR `auto_advance` depending on flags/config. -## 14. Auto-Advance Check +## 15. Auto-Advance Check Check for auto-advance trigger: @@ -478,7 +751,7 @@ Plans ready. Launching execute-phase... Launch execute-phase using the skill tool to avoid nested task sessions (which cause runtime freezes due to deep agent nesting): ``` -skill(skill="gsd-execute-phase", args="${PHASE} --auto --no-transition") +skill(skill="gsd-execute-phase", args="${PHASE} --auto --no-transition ${GSD_WS}") ``` The `--no-transition` flag tells execute-phase to return status after verification instead of chaining further. This keeps the auto-advance chain flat — each phase runs at the same nesting level rather than spawning deeper task agents. @@ -492,14 +765,14 @@ The `--no-transition` flag tells execute-phase to return status after verificati Auto-advance pipeline finished. - Next: /gsd-discuss-phase ${NEXT_PHASE} --auto + Next: /gsd-discuss-phase ${NEXT_PHASE} --auto ${GSD_WS} ``` - **GAPS FOUND / VERIFICATION FAILED** → Display result, stop chain: ``` Auto-advance stopped: Execution needs review. Review the output above and continue manually: - /gsd-execute-phase ${PHASE} + /gsd-execute-phase ${PHASE} ${GSD_WS} ``` **If neither `--auto` nor config enabled:** @@ -530,7 +803,7 @@ Verification: {Passed | Passed with override | Skipped} **Execute Phase {X}** — run all {N} plans -/gsd-execute-phase {X} +/gsd-execute-phase {X} ${GSD_WS} */new first → fresh context window* @@ -539,10 +812,36 @@ Verification: {Passed | Passed with override | Skipped} **Also available:** - cat .planning/phases/{phase-dir}/*-PLAN.md — review plans - /gsd-plan-phase {X} --research — re-research first +- /gsd-review --phase {X} --all — peer review plans with external AIs +- /gsd-plan-phase {X} --reviews — replan incorporating review feedback ─────────────────────────────────────────────────────────────── + +**Windows users:** If plan-phase freezes during agent spawning (common on Windows due to +stdio deadlocks with MCP servers — see OpenCode issue anthropics/OpenCode-code#28126): + +1. **Force-kill:** Close the terminal (Ctrl+C may not work) +2. **Clean up orphaned processes:** + ```powershell + # Kill orphaned node processes from stale MCP servers + Get-Process node -ErrorAction SilentlyContinue | Where-Object {$_.StartTime -lt (Get-Date).AddHours(-1)} | Stop-Process -Force + ``` +3. **Clean up stale task directories:** + ```powershell + # Remove stale subagent task dirs (OpenCode never cleans these on crash) + Remove-Item -Recurse -Force "$env:USERPROFILE\.OpenCode\tasks\*" -ErrorAction SilentlyContinue + ``` +4. **Reduce MCP server count:** Temporarily disable non-essential MCP servers in settings.json +5. **Retry:** Restart OpenCode and run `/gsd-plan-phase` again + +If freezes persist, try `--skip-research` to reduce the agent chain from 3 to 2 agents: +``` +/gsd-plan-phase N --skip-research +``` + + - [ ] .planning/ directory validated - [ ] Phase validated against roadmap diff --git a/gsd-opencode/get-shit-done/workflows/plant-seed.md b/gsd-opencode/get-shit-done/workflows/plant-seed.md new file mode 100644 index 0000000..b5c931a --- /dev/null +++ b/gsd-opencode/get-shit-done/workflows/plant-seed.md @@ -0,0 +1,169 @@ + +Capture a forward-looking idea as a structured seed file with trigger conditions. +Seeds auto-surface during /gsd-new-milestone when trigger conditions match the +new milestone's scope. + +Seeds beat deferred items because they: +- Preserve WHY the idea matters (not just WHAT) +- Define WHEN to surface (trigger conditions, not manual scanning) +- Track breadcrumbs (code references, related decisions) +- Auto-present at the right time via new-milestone scan + + + + + +Parse `$ARGUMENTS` for the idea summary. + +If empty, ask: +``` +What's the idea? (one sentence) +``` + +Store as `$IDEA`. + + + +```bash +mkdir -p .planning/seeds +``` + + + +Ask focused questions to build a complete seed: + +``` +question( + header: "Trigger", + question: "When should this idea surface? (e.g., 'when we add user accounts', 'next major version', 'when performance becomes a priority')", + options: [] // freeform +) +``` + +Store as `$TRIGGER`. + +``` +question( + header: "Why", + question: "Why does this matter? What problem does it solve or what opportunity does it create?", + options: [] +) +``` + +Store as `$WHY`. + +``` +question( + header: "Scope", + question: "How big is this? (rough estimate)", + options: [ + { label: "Small", description: "A few hours — could be a quick task" }, + { label: "Medium", description: "A phase or two — needs planning" }, + { label: "Large", description: "A full milestone — significant effort" } + ] +) +``` + +Store as `$SCOPE`. + + + +Search the codebase for relevant references: + +```bash +# Find files related to the idea keywords +grep -rl "$KEYWORD" --include="*.ts" --include="*.js" --include="*.md" . 2>/dev/null | head -10 +``` + +Also check: +- Current STATE.md for related decisions +- ROADMAP.md for related phases +- todos/ for related captured ideas + +Store relevant file paths as `$BREADCRUMBS`. + + + +```bash +# Find next seed number +EXISTING=$( (ls .planning/seeds/SEED-*.md 2>/dev/null || true) | wc -l ) +NEXT=$((EXISTING + 1)) +PADDED=$(printf "%03d" $NEXT) +``` + +Generate slug from idea summary. + + + +write `.planning/seeds/SEED-{PADDED}-{slug}.md`: + +```markdown +--- +id: SEED-{PADDED} +status: dormant +planted: {ISO date} +planted_during: {current milestone/phase from STATE.md} +trigger_when: {$TRIGGER} +scope: {$SCOPE} +--- + +# SEED-{PADDED}: {$IDEA} + +## Why This Matters + +{$WHY} + +## When to Surface + +**Trigger:** {$TRIGGER} + +This seed should be presented during `/gsd-new-milestone` when the milestone +scope matches any of these conditions: +- {trigger condition 1} +- {trigger condition 2} + +## Scope Estimate + +**{$SCOPE}** — {elaboration based on scope choice} + +## Breadcrumbs + +Related code and decisions found in the current codebase: + +{list of $BREADCRUMBS with file paths} + +## Notes + +{any additional context from the current session} +``` + + + +```bash +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: plant seed — {$IDEA}" --files .planning/seeds/SEED-{PADDED}-{slug}.md +``` + + + +``` +✅ Seed planted: SEED-{PADDED} + +"{$IDEA}" +Trigger: {$TRIGGER} +Scope: {$SCOPE} +File: .planning/seeds/SEED-{PADDED}-{slug}.md + +This seed will surface automatically when you run /gsd-new-milestone +and the milestone scope matches the trigger condition. +``` + + + + + +- [ ] Seed file created in .planning/seeds/ +- [ ] Frontmatter includes status, trigger, scope +- [ ] Breadcrumbs collected from codebase +- [ ] Committed to git +- [ ] User shown confirmation with trigger info + diff --git a/gsd-opencode/get-shit-done/workflows/pr-branch.md b/gsd-opencode/get-shit-done/workflows/pr-branch.md new file mode 100644 index 0000000..b57c6fe --- /dev/null +++ b/gsd-opencode/get-shit-done/workflows/pr-branch.md @@ -0,0 +1,129 @@ + +Create a clean branch for pull requests by filtering out .planning/ commits. +The PR branch contains only code changes — reviewers don't see GSD artifacts +(PLAN.md, SUMMARY.md, STATE.md, CONTEXT.md, etc.). + +Uses git cherry-pick with path filtering to rebuild a clean history. + + + + + +Parse `$ARGUMENTS` for target branch (default: `main`). + +```bash +CURRENT_BRANCH=$(git branch --show-current) +TARGET=${1:-main} +``` + +Check preconditions: +- Must be on a feature branch (not main/master) +- Must have commits ahead of target + +```bash +AHEAD=$(git rev-list --count "$TARGET".."$CURRENT_BRANCH" 2>/dev/null) +if [ "$AHEAD" = "0" ]; then + echo "No commits ahead of $TARGET — nothing to filter." + exit 0 +fi +``` + +Display: +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► PR BRANCH +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Branch: {CURRENT_BRANCH} +Target: {TARGET} +Commits: {AHEAD} ahead +``` + + + +Classify commits: + +```bash +# Get all commits ahead of target +git log --oneline "$TARGET".."$CURRENT_BRANCH" --no-merges +``` + +For each commit, check if it ONLY touches .planning/ files: + +```bash +# For each commit hash +FILES=$(git diff-tree --no-commit-id --name-only -r $HASH) +ALL_PLANNING=$(echo "$FILES" | grep -v "^\.planning/" | wc -l) +``` + +Classify: +- **Code commits**: Touch at least one non-.planning/ file → INCLUDE +- **Planning-only commits**: Touch only .planning/ files → EXCLUDE +- **Mixed commits**: Touch both → INCLUDE (planning changes come along) + +Display analysis: +``` +Commits to include: {N} (code changes) +Commits to exclude: {N} (planning-only) +Mixed commits: {N} (code + planning — included) +``` + + + +```bash +PR_BRANCH="${CURRENT_BRANCH}-pr" + +# Create PR branch from target +git checkout -b "$PR_BRANCH" "$TARGET" +``` + +Cherry-pick only code commits (in order): + +```bash +for HASH in $CODE_COMMITS; do + git cherry-pick "$HASH" --no-commit + # Remove any .planning/ files that came along in mixed commits + git rm -r --cached .planning/ 2>/dev/null || true + git commit -C "$HASH" +done +``` + +Return to original branch: +```bash +git checkout "$CURRENT_BRANCH" +``` + + + +```bash +# Verify no .planning/ files in PR branch +PLANNING_FILES=$(git diff --name-only "$TARGET".."$PR_BRANCH" | grep "^\.planning/" | wc -l) +TOTAL_FILES=$(git diff --name-only "$TARGET".."$PR_BRANCH" | wc -l) +PR_COMMITS=$(git rev-list --count "$TARGET".."$PR_BRANCH") +``` + +Display results: +``` +✅ PR branch created: {PR_BRANCH} + +Original: {AHEAD} commits, {ORIGINAL_FILES} files +PR branch: {PR_COMMITS} commits, {TOTAL_FILES} files +Planning files: {PLANNING_FILES} (should be 0) + +Next steps: + git push origin {PR_BRANCH} + gh pr create --base {TARGET} --head {PR_BRANCH} + +Or use /gsd-ship to create the PR automatically. +``` + + + + + +- [ ] PR branch created from target +- [ ] Planning-only commits excluded +- [ ] No .planning/ files in PR branch diff +- [ ] Commit messages preserved from original +- [ ] User shown next steps + diff --git a/gsd-opencode/get-shit-done/workflows/profile-user.md b/gsd-opencode/get-shit-done/workflows/profile-user.md new file mode 100644 index 0000000..98970f9 --- /dev/null +++ b/gsd-opencode/get-shit-done/workflows/profile-user.md @@ -0,0 +1,450 @@ + +Orchestrate the full developer profiling flow: consent, session analysis (or questionnaire fallback), profile generation, result display, and artifact creation. + +This workflow wires Phase 1 (session pipeline) and Phase 2 (profiling engine) into a cohesive user-facing experience. All heavy lifting is done by existing gsd-tools.cjs subcommands and the gsd-user-profiler agent -- this workflow orchestrates the sequence, handles branching, and provides the UX. + + + +read all files referenced by the invoking prompt's execution_context before starting. + +Key references: +- @$HOME/.config/opencode/get-shit-done/references/ui-brand.md (display patterns) +- @$HOME/.config/opencode/get-shit-done/agents/gsd-user-profiler.md (profiler agent definition) +- @$HOME/.config/opencode/get-shit-done/references/user-profiling.md (profiling reference doc) + + + + +## 1. Initialize + +Parse flags from $ARGUMENTS: +- Detect `--questionnaire` flag (skip session analysis, questionnaire-only) +- Detect `--refresh` flag (rebuild profile even when one exists) + +Check for existing profile: + +```bash +PROFILE_PATH="$HOME/.config/opencode/get-shit-done/USER-PROFILE.md" +[ -f "$PROFILE_PATH" ] && echo "EXISTS" || echo "NOT_FOUND" +``` + +**If profile exists AND --refresh NOT set AND --questionnaire NOT set:** + +Use question: +- header: "Existing Profile" +- question: "You already have a profile. What would you like to do?" +- options: + - "View it" -- Display summary card from existing profile data, then exit + - "Refresh it" -- Continue with --refresh behavior + - "Cancel" -- Exit workflow + +If "View it": read USER-PROFILE.md, display its content formatted as a summary card, then exit. +If "Refresh it": Set --refresh behavior and continue. +If "Cancel": Display "No changes made." and exit. + +**If profile exists AND --refresh IS set:** + +Backup existing profile: +```bash +cp "$HOME/.config/opencode/get-shit-done/USER-PROFILE.md" "$HOME/.config/opencode/get-shit-done/USER-PROFILE.backup.md" +``` + +Display: "Re-analyzing your sessions to update your profile." +Continue to step 2. + +**If no profile exists:** Continue to step 2. + +--- + +## 2. Consent Gate (ACTV-06) + +**Skip if** `--questionnaire` flag is set (no JSONL reading occurs -- jump directly to step 4b). + +Display consent screen: + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD > PROFILE YOUR CODING STYLE +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +OpenCode starts every conversation generic. A profile teaches OpenCode +how YOU actually work -- not how you think you work. + +## What We'll Analyze + +Your recent OpenCode sessions, looking for patterns in these +8 behavioral dimensions: + +| Dimension | What It Measures | +|----------------------|---------------------------------------------| +| Communication Style | How you phrase requests (terse vs. detailed) | +| Decision Speed | How you choose between options | +| Explanation Depth | How much explanation you want with code | +| Debugging Approach | How you tackle errors and bugs | +| UX Philosophy | How much you care about design vs. function | +| Vendor Philosophy | How you evaluate libraries and tools | +| Frustration Triggers | What makes you correct OpenCode | +| Learning Style | How you prefer to learn new things | + +## Data Handling + +✓ Reads session files locally (read-only, nothing modified) +✓ Analyzes message patterns (not content meaning) +✓ Stores profile at $HOME/.config/opencode/get-shit-done/USER-PROFILE.md +✗ Nothing is sent to external services +✗ Sensitive content (API keys, passwords) is automatically excluded +``` + +**If --refresh path:** +Show abbreviated consent instead: + +``` +Re-analyzing your sessions to update your profile. +Your existing profile has been backed up to USER-PROFILE.backup.md. +``` + +Use question: +- header: "Refresh" +- question: "Continue with profile refresh?" +- options: + - "Continue" -- Proceed to step 3 + - "Cancel" -- Exit workflow + +**If default (no --refresh) path:** + +Use question: +- header: "Ready?" +- question: "Ready to analyze your sessions?" +- options: + - "Let's go" -- Proceed to step 3 (session analysis) + - "Use questionnaire instead" -- Jump to step 4b (questionnaire path) + - "Not now" -- Display "No worries. Run /gsd-profile-user when ready." and exit + +--- + +## 3. Session Scan + +Display: "◆ Scanning sessions..." + +Run session scan: +```bash +SCAN_RESULT=$(node $HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs scan-sessions --json 2>/dev/null) +``` + +Parse the JSON output to get session count and project count. + +Display: "✓ Found N sessions across M projects" + +**Determine data sufficiency:** +- Count total messages available from the scan result (sum sessions across projects) +- If 0 sessions found: Display "No sessions found. Switching to questionnaire." and jump to step 4b +- If sessions found: Continue to step 4a + +--- + +## 4a. Session Analysis Path + +Display: "◆ Sampling messages..." + +Run profile sampling: +```bash +SAMPLE_RESULT=$(node $HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs profile-sample --json 2>/dev/null) +``` + +Parse the JSON output to get the temp directory path and message count. + +Display: "✓ Sampled N messages from M projects" + +Display: "◆ Analyzing patterns..." + +**Spawn gsd-user-profiler agent using task tool:** + +Use the task tool to spawn the `gsd-user-profiler` agent. Provide it with: +- The sampled JSONL file path from profile-sample output +- The user-profiling reference doc at `$HOME/.config/opencode/get-shit-done/references/user-profiling.md` + +The agent prompt should follow this structure: +``` +read the profiling reference document and the sampled session messages, then analyze the developer's behavioral patterns across all 8 dimensions. + +Reference: @$HOME/.config/opencode/get-shit-done/references/user-profiling.md +Session data: @{temp_dir}/profile-sample.jsonl + +Analyze these messages and return your analysis in the JSON format specified in the reference document. +``` + +**Parse the agent's output:** +- Extract the `` JSON block from the agent's response +- Save analysis JSON to a temp file (in the same temp directory created by profile-sample) + +```bash +ANALYSIS_PATH="{temp_dir}/analysis.json" +``` + +write the analysis JSON to `$ANALYSIS_PATH`. + +Display: "✓ Analysis complete (N dimensions scored)" + +**Check for thin data:** +- read the analysis JSON and check the total message count +- If < 50 messages were analyzed: Note that a questionnaire supplement could improve accuracy. Display: "Note: Limited session data (N messages). Results may have lower confidence." + +Continue to step 5. + +--- + +## 4b. Questionnaire Path + +Display: "Using questionnaire to build your profile." + +**Get questions:** +```bash +QUESTIONS=$(node $HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs profile-questionnaire --json 2>/dev/null) +``` + +Parse the questions JSON. It contains 8 questions, one per dimension. + +**Present each question to the user via question:** + +For each question in the questions array: +- header: The dimension name (e.g., "Communication Style") +- question: The question text +- options: The answer options from the question definition + +Collect all answers into an answers JSON object mapping dimension keys to selected answer values. + +**Save answers to temp file:** +```bash +ANSWERS_PATH=$(mktemp /tmp/gsd-profile-answers-XXXXXX.json) +``` + +write the answers JSON to `$ANSWERS_PATH`. + +**Convert answers to analysis:** +```bash +ANALYSIS_RESULT=$(node $HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs profile-questionnaire --answers "$ANSWERS_PATH" --json 2>/dev/null) +``` + +Parse the analysis JSON from the result. + +Save analysis JSON to a temp file: +```bash +ANALYSIS_PATH=$(mktemp /tmp/gsd-profile-analysis-XXXXXX.json) +``` + +write the analysis JSON to `$ANALYSIS_PATH`. + +Continue to step 5 (skip split resolution since questionnaire handles ambiguity internally). + +--- + +## 5. Split Resolution + +**Skip if** questionnaire-only path (splits already handled internally). + +read the analysis JSON from `$ANALYSIS_PATH`. + +Check each dimension for `cross_project_consistent: false`. + +**For each split detected:** + +Use question: +- header: The dimension name (e.g., "Communication Style") +- question: "Your sessions show different patterns:" followed by the split context (e.g., "CLI/backend projects -> terse-direct, Frontend/UI projects -> detailed-structured") +- options: + - Rating option A (e.g., "terse-direct") + - Rating option B (e.g., "detailed-structured") + - "Context-dependent (keep both)" + +**If user picks a specific rating:** Update the dimension's `rating` field in the analysis JSON to the selected value. + +**If user picks "Context-dependent":** Keep the dominant rating in the `rating` field. Add a `context_note` to the dimension's summary describing the split (e.g., "Context-dependent: terse in CLI projects, detailed in frontend projects"). + +write updated analysis JSON back to `$ANALYSIS_PATH`. + +--- + +## 6. Profile write + +Display: "◆ Writing profile..." + +```bash +node $HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs write-profile --input "$ANALYSIS_PATH" --json 2>/dev/null +``` + +Display: "✓ Profile written to $HOME/.config/opencode/get-shit-done/USER-PROFILE.md" + +--- + +## 7. Result Display + +read the analysis JSON from `$ANALYSIS_PATH` to build the display. + +**Show report card table:** + +``` +## Your Profile + +| Dimension | Rating | Confidence | +|----------------------|----------------------|------------| +| Communication Style | detailed-structured | HIGH | +| Decision Speed | deliberate-informed | MEDIUM | +| Explanation Depth | concise | HIGH | +| Debugging Approach | hypothesis-driven | MEDIUM | +| UX Philosophy | pragmatic | LOW | +| Vendor Philosophy | thorough-evaluator | HIGH | +| Frustration Triggers | scope-creep | MEDIUM | +| Learning Style | self-directed | HIGH | +``` + +(Populate with actual values from the analysis JSON.) + +**Show highlight reel:** + +Pick 3-4 dimensions with the highest confidence and most evidence signals. Format as: + +``` +## Highlights + +- **Communication (HIGH):** You consistently provide structured context with + headers and problem statements before making requests +- **Vendor Choices (HIGH):** You research alternatives thoroughly -- comparing + docs, GitHub activity, and bundle sizes before committing +- **Frustrations (MEDIUM):** You correct OpenCode most often for doing things + you didn't ask for -- scope creep is your primary trigger +``` + +Build highlights from the `evidence` array and `summary` fields in the analysis JSON. Use the most compelling evidence quotes. Format each as "You tend to..." or "You consistently..." with evidence attribution. + +**Offer full profile view:** + +Use question: +- header: "Profile" +- question: "Want to see the full profile?" +- options: + - "Yes" -- read and display the full USER-PROFILE.md content, then continue to step 8 + - "Continue to artifacts" -- Proceed directly to step 8 + +--- + +## 8. Artifact Selection (ACTV-05) + +Use question with multiSelect: +- header: "Artifacts" +- question: "Which artifacts should I generate?" +- options (ALL pre-selected by default): + - "/gsd-dev-preferences command file" -- "Load your preferences in any session" + - "AGENTS.md profile section" -- "Add profile to this project's AGENTS.md" + - "Global AGENTS.md" -- "Add profile to $HOME/.OpenCode/AGENTS.md for all projects" + +**If no artifacts selected:** Display "No artifacts generated. Your profile is saved at $HOME/.config/opencode/get-shit-done/USER-PROFILE.md" and jump to step 10. + +--- + +## 9. Artifact Generation + +Generate selected artifacts sequentially (file I/O is fast, no benefit from parallel agents): + +**For /gsd-dev-preferences (if selected):** + +```bash +node $HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs generate-dev-preferences --analysis "$ANALYSIS_PATH" --json 2>/dev/null +``` + +Display: "✓ Generated /gsd-dev-preferences at $HOME/.OpenCode/commands/gsd/dev-preferences.md" + +**For AGENTS.md profile section (if selected):** + +```bash +node $HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs generate-OpenCode-profile --analysis "$ANALYSIS_PATH" --json 2>/dev/null +``` + +Display: "✓ Added profile section to AGENTS.md" + +**For Global AGENTS.md (if selected):** + +```bash +node $HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs generate-OpenCode-profile --analysis "$ANALYSIS_PATH" --global --json 2>/dev/null +``` + +Display: "✓ Added profile section to $HOME/.OpenCode/AGENTS.md" + +**Error handling:** If any gsd-tools.cjs call fails, display the error message and use question to offer "Retry" or "Skip this artifact". On retry, re-run the command. On skip, continue to next artifact. + +--- + +## 10. Summary & Refresh Diff + +**If --refresh path:** + +read both old backup and new analysis to compare dimension ratings/confidence. + +read the backed-up profile: +```bash +BACKUP_PATH="$HOME/.config/opencode/get-shit-done/USER-PROFILE.backup.md" +``` + +Compare each dimension's rating and confidence between old and new. Display diff table showing only changed dimensions: + +``` +## Changes + +| Dimension | Before | After | +|-----------------|-----------------------------|-----------------------------| +| Communication | terse-direct (LOW) | detailed-structured (HIGH) | +| Debugging | fix-first (MEDIUM) | hypothesis-driven (MEDIUM) | +``` + +If nothing changed: Display "No changes detected -- your profile is already up to date." + +**Display final summary:** + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD > PROFILE COMPLETE ✓ +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Your profile: $HOME/.config/opencode/get-shit-done/USER-PROFILE.md +``` + +Then list paths for each generated artifact: +``` +Artifacts: + ✓ /gsd-dev-preferences $HOME/.OpenCode/commands/gsd/dev-preferences.md + ✓ AGENTS.md section ./AGENTS.md + ✓ Global AGENTS.md $HOME/.OpenCode/AGENTS.md +``` + +(Only show artifacts that were actually generated.) + +**Clean up temp files:** + +Remove the temp directory created by profile-sample (contains sample JSONL and analysis JSON): +```bash +rm -rf "$TEMP_DIR" +``` + +Also remove any standalone temp files created for questionnaire answers: +```bash +rm -f "$ANSWERS_PATH" 2>/dev/null +rm -f "$ANALYSIS_PATH" 2>/dev/null +``` + +(Only clean up temp paths that were actually created during this workflow run.) + + + + +- [ ] Initialization detects existing profile and handles all three responses (view/refresh/cancel) +- [ ] Consent gate shown for session analysis path, skipped for questionnaire path +- [ ] Session scan discovers sessions and reports statistics +- [ ] Session analysis path: samples messages, spawns profiler agent, extracts analysis JSON +- [ ] Questionnaire path: presents 8 questions, collects answers, converts to analysis JSON +- [ ] Split resolution presents context-dependent splits with user resolution options +- [ ] Profile written to USER-PROFILE.md via write-profile subcommand +- [ ] Result display shows report card table and highlight reel with evidence +- [ ] Artifact selection uses multiSelect with all options pre-selected +- [ ] Artifacts generated sequentially via gsd-tools.cjs subcommands +- [ ] Refresh diff shows changed dimensions when --refresh was used +- [ ] Temp files cleaned up on completion + diff --git a/gsd-opencode/get-shit-done/workflows/progress.md b/gsd-opencode/get-shit-done/workflows/progress.md index 1164377..9dc9158 100644 --- a/gsd-opencode/get-shit-done/workflows/progress.md +++ b/gsd-opencode/get-shit-done/workflows/progress.md @@ -1,6 +1,6 @@ - + Check project progress, summarize recent work and what's ahead, then intelligently route to the next action — either executing an existing plan or creating the next one. Provides situational awareness before continuing work. - + read all files referenced by the invoking prompt's execution_context before starting. @@ -18,6 +18,10 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi Extract from init JSON: `project_exists`, `roadmap_exists`, `state_exists`, `phases`, `current_phase`, `next_phase`, `milestone_version`, `completed_count`, `phase_count`, `paused_at`, `state_path`, `roadmap_path`, `project_path`, `config_path`. +```bash +DISCUSS_MODE=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.discuss_mode 2>/dev/null || echo "discuss") +``` + If `project_exists` is false (no `.planning/` directory): ``` @@ -81,7 +85,7 @@ Use this instead of manually reading/parsing ROADMAP.md. - Use `current_phase` and `next_phase` from `$ROADMAP` - Note `paused_at` if work was paused (from `$STATE`) - Count pending todos: use `init todos` or `list-todos` -- Check for active debug sessions: `ls .planning/debug/*.md 2>/dev/null | grep -v resolved | wc -l` +- Check for active debug sessions: `(ls .planning/debug/*.md 2>/dev/null || true) | grep -v resolved | wc -l` @@ -98,7 +102,8 @@ Present: # [Project Name] **Progress:** {PROGRESS_BAR} -**Profile:** [simple/smart/genius] +**Profile:** [simple/smart/genius/inherit] +**Discuss mode:** {DISCUSS_MODE} ## Recent Work - [Phase X, Plan Y]: [what was accomplished - 1 line from summary-extract] @@ -138,9 +143,9 @@ CONTEXT: [✓ if has_context | - if not] List files in the current phase directory: ```bash -ls -1 .planning/phases/[current-phase-dir]/*-PLAN.md 2>/dev/null | wc -l -ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null | wc -l -ls -1 .planning/phases/[current-phase-dir]/*-UAT.md 2>/dev/null | wc -l +(ls -1 .planning/phases/[current-phase-dir]/*-PLAN.md 2>/dev/null || true) | wc -l +(ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null || true) | wc -l +(ls -1 .planning/phases/[current-phase-dir]/*-UAT.md 2>/dev/null || true) | wc -l ``` State: "This phase has {X} plans, {Y} summaries." @@ -150,17 +155,47 @@ State: "This phase has {X} plans, {Y} summaries." Check for UAT.md files with status "diagnosed" (has gaps needing fixes). ```bash -# Check for diagnosed UAT with gaps -grep -l "status: diagnosed" .planning/phases/[current-phase-dir]/*-UAT.md 2>/dev/null +# Check for diagnosed UAT with gaps or partial (incomplete) testing +grep -l "status: diagnosed\|status: partial" .planning/phases/[current-phase-dir]/*-UAT.md 2>/dev/null || true ``` Track: - `uat_with_gaps`: UAT.md files with status "diagnosed" (gaps need fixing) +- `uat_partial`: UAT.md files with status "partial" (incomplete testing) + +**Step 1.6: Cross-phase health check** + +Scan ALL phases in the current milestone for outstanding verification debt using the CLI (which respects milestone boundaries via `getMilestonePhaseFilter`): + +```bash +DEBT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" audit-uat --raw 2>/dev/null) +``` + +Parse JSON for `summary.total_items` and `summary.total_files`. + +Track: `outstanding_debt` — `summary.total_items` from the audit. + +**If outstanding_debt > 0:** Add a warning section to the progress report output (in the `report` step), placed between "## What's Next" and the route suggestion: + +```markdown +## Verification Debt ({N} files across prior phases) + +| Phase | File | Issue | +|-------|------|-------| +| {phase} | {filename} | {pending_count} pending, {skipped_count} skipped, {blocked_count} blocked | +| {phase} | {filename} | human_needed — {count} items | + +Review: `/gsd-audit-uat ${GSD_WS}` — full cross-phase audit +Resume testing: `/gsd-verify-work {phase} ${GSD_WS}` — retest specific phase +``` + +This is a WARNING, not a blocker — routing proceeds normally. The debt is visible so the user can make an informed choice. **Step 2: Route based on counts** | Condition | Meaning | Action | |-----------|---------|--------| +| uat_partial > 0 | UAT testing incomplete | Go to **Route E.2** | | uat_with_gaps > 0 | UAT gaps need fix plans | Go to **Route E** | | summaries < plans | Unexecuted plans exist | Go to **Route A** | | summaries = plans AND plans > 0 | Phase complete | Go to Step 3 | @@ -180,7 +215,7 @@ read its `` section. **{phase}-{plan}: [Plan Name]** — [objective summary from PLAN.md] -`/gsd-execute-phase {phase}` +`/gsd-execute-phase {phase} ${GSD_WS}` *`/new` first → fresh context window* @@ -193,6 +228,13 @@ read its `` section. Check if `{phase_num}-CONTEXT.md` exists in phase directory. +Check if current phase has UI indicators: + +```bash +PHASE_SECTION=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "${CURRENT_PHASE}" 2>/dev/null) +PHASE_HAS_UI=$(echo "$PHASE_SECTION" | grep -qi "UI hint.*yes" && echo "true" || echo "false") +``` + **If CONTEXT.md exists:** ``` @@ -203,14 +245,14 @@ Check if `{phase_num}-CONTEXT.md` exists in phase directory. **Phase {N}: {Name}** — {Goal from ROADMAP.md} *✓ Context gathered, ready to plan* -`/gsd-plan-phase {phase-number}` +`/gsd-plan-phase {phase-number} ${GSD_WS}` *`/new` first → fresh context window* --- ``` -**If CONTEXT.md does NOT exist:** +**If CONTEXT.md does NOT exist AND phase has UI (`PHASE_HAS_UI` is `true`):** ``` --- @@ -226,12 +268,35 @@ Check if `{phase_num}-CONTEXT.md` exists in phase directory. --- **Also available:** +- `/gsd-ui-phase {phase}` — generate UI design contract (recommended for frontend phases) - `/gsd-plan-phase {phase}` — skip discussion, plan directly - `/gsd-list-phase-assumptions {phase}` — see OpenCode's assumptions --- ``` +**If CONTEXT.md does NOT exist AND phase has no UI:** + +``` +--- + +## ▶ Next Up + +**Phase {N}: {Name}** — {Goal from ROADMAP.md} + +`/gsd-discuss-phase {phase} ${GSD_WS}` — gather context and clarify approach + +*`/new` first → fresh context window* + +--- + +**Also available:** +- `/gsd-plan-phase {phase} ${GSD_WS}` — skip discussion, plan directly +- `/gsd-list-phase-assumptions {phase} ${GSD_WS}` — see OpenCode's assumptions + +--- +``` + --- **Route E: UAT gaps need fix plans** @@ -245,15 +310,41 @@ UAT.md exists with gaps (diagnosed issues). User needs to plan fixes. **{phase_num}-UAT.md** has {N} gaps requiring fixes. -`/gsd-plan-phase {phase} --gaps` +`/gsd-plan-phase {phase} --gaps ${GSD_WS}` + +*`/new` first → fresh context window* + +--- + +**Also available:** +- `/gsd-execute-phase {phase} ${GSD_WS}` — execute phase plans +- `/gsd-verify-work {phase} ${GSD_WS}` — run more UAT testing + +--- +``` + +--- + +**Route E.2: UAT testing incomplete (partial)** + +UAT.md exists with `status: partial` — testing session ended before all items resolved. + +``` +--- + +## Incomplete UAT Testing + +**{phase_num}-UAT.md** has {N} unresolved tests (pending, blocked, or skipped). + +`/gsd-verify-work {phase} ${GSD_WS}` — resume testing from where you left off *`/new` first → fresh context window* --- **Also available:** -- `/gsd-execute-phase {phase}` — execute phase plans -- `/gsd-verify-work {phase}` — run more UAT testing +- `/gsd-audit-uat ${GSD_WS}` — full cross-phase UAT audit +- `/gsd-execute-phase {phase} ${GSD_WS}` — execute phase plans --- ``` @@ -283,6 +374,15 @@ State: "Current phase is {X}. Milestone has {N} phases (highest: {Y})." read ROADMAP.md to get the next phase's name and goal. +Check if next phase has UI indicators: + +```bash +NEXT_PHASE_SECTION=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "$((Z+1))" 2>/dev/null) +NEXT_HAS_UI=$(echo "$NEXT_PHASE_SECTION" | grep -qi "UI hint.*yes" && echo "true" || echo "false") +``` + +**If next phase has UI (`NEXT_HAS_UI` is `true`):** + ``` --- @@ -299,12 +399,37 @@ read ROADMAP.md to get the next phase's name and goal. --- **Also available:** +- `/gsd-ui-phase {Z+1}` — generate UI design contract (recommended for frontend phases) - `/gsd-plan-phase {Z+1}` — skip discussion, plan directly - `/gsd-verify-work {Z}` — user acceptance test before continuing --- ``` +**If next phase has no UI:** + +``` +--- + +## ✓ Phase {Z} Complete + +## ▶ Next Up + +**Phase {Z+1}: {Name}** — {Goal from ROADMAP.md} + +`/gsd-discuss-phase {Z+1} ${GSD_WS}` — gather context and clarify approach + +*`/new` first → fresh context window* + +--- + +**Also available:** +- `/gsd-plan-phase {Z+1} ${GSD_WS}` — skip discussion, plan directly +- `/gsd-verify-work {Z} ${GSD_WS}` — user acceptance test before continuing + +--- +``` + --- **Route D: Milestone complete** @@ -320,14 +445,14 @@ All {N} phases finished! **Complete Milestone** — archive and prepare for next -`/gsd-complete-milestone` +`/gsd-complete-milestone ${GSD_WS}` *`/new` first → fresh context window* --- **Also available:** -- `/gsd-verify-work` — user acceptance test before completing milestone +- `/gsd-verify-work ${GSD_WS}` — user acceptance test before completing milestone --- ``` @@ -351,7 +476,7 @@ Ready to plan the next milestone. **Start Next Milestone** — questioning → research → requirements → roadmap -`/gsd-new-milestone` +`/gsd-new-milestone ${GSD_WS}` *`/new` first → fresh context window* @@ -363,10 +488,10 @@ Ready to plan the next milestone. **Handle edge cases:** -- Phase complete but next phase not planned → offer `/gsd-plan-phase [next]` +- Phase complete but next phase not planned → offer `/gsd-plan-phase [next] ${GSD_WS}` - All work complete → offer milestone completion - Blockers present → highlight before offering to continue -- Handoff file exists → mention it, offer `/gsd-resume-work` +- Handoff file exists → mention it, offer `/gsd-resume-work ${GSD_WS}` diff --git a/gsd-opencode/get-shit-done/workflows/quick.md b/gsd-opencode/get-shit-done/workflows/quick.md index 450af32..e0e7835 100644 --- a/gsd-opencode/get-shit-done/workflows/quick.md +++ b/gsd-opencode/get-shit-done/workflows/quick.md @@ -1,23 +1,35 @@ - + Execute small, ad-hoc tasks with GSD guarantees (atomic commits, STATE.md tracking). Quick mode spawns gsd-planner (quick mode) + gsd-executor(s), tracks tasks in `.planning/quick/`, and updates STATE.md's "Quick Tasks Completed" table. With `--discuss` flag: lightweight discussion phase before planning. Surfaces assumptions, clarifies gray areas, captures decisions in CONTEXT.md so the planner treats them as locked. With `--full` flag: enables plan-checking (max 2 iterations) and post-execution verification for quality guarantees without full milestone ceremony. -Flags are composable: `--discuss --full` gives discussion + plan-checking + verification. - +With `--research` flag: spawns a focused research agent before planning. Investigates implementation approaches, library options, and pitfalls. Use when you're unsure how to approach a task. + +Flags are composable: `--discuss --research --full` gives discussion + research + plan-checking + verification. + read all files referenced by the invoking prompt's execution_context before starting. + +Valid GSD subagent types (use exact names — do not fall back to 'general'): +- gsd-phase-researcher — Researches technical approaches for a phase +- gsd-planner — Creates detailed plans from phase scope +- gsd-plan-checker — Reviews plan quality before execution +- gsd-executor — Executes plan tasks, commits, creates SUMMARY.md +- gsd-verifier — Verifies phase completion, checks quality gates + + **Step 1: Parse arguments and get task description** Parse `$ARGUMENTS` for: - `--full` flag → store as `$FULL_MODE` (true/false) - `--discuss` flag → store as `$DISCUSS_MODE` (true/false) +- `--research` flag → store as `$RESEARCH_MODE` (true/false) - Remaining text → use as `$DESCRIPTION` if non-empty If `$DESCRIPTION` is empty after parsing, prompt user interactively: @@ -36,7 +48,16 @@ If still empty, re-prompt: "Please provide a task description." Display banner based on active flags: -If `$DISCUSS_MODE` and `$FULL_MODE`: +If `$DISCUSS_MODE` and `$RESEARCH_MODE` and `$FULL_MODE`: +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► QUICK TASK (DISCUSS + RESEARCH + FULL) +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +◆ Discussion + research + plan checking + verification enabled +``` + +If `$DISCUSS_MODE` and `$FULL_MODE` (no research): ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► QUICK TASK (DISCUSS + FULL) @@ -45,6 +66,24 @@ If `$DISCUSS_MODE` and `$FULL_MODE`: ◆ Discussion + plan checking + verification enabled ``` +If `$DISCUSS_MODE` and `$RESEARCH_MODE` (no full): +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► QUICK TASK (DISCUSS + RESEARCH) +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +◆ Discussion + research enabled +``` + +If `$RESEARCH_MODE` and `$FULL_MODE` (no discuss): +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► QUICK TASK (RESEARCH + FULL) +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +◆ Research + plan checking + verification enabled +``` + If `$DISCUSS_MODE` only: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ @@ -54,6 +93,15 @@ If `$DISCUSS_MODE` only: ◆ Discussion phase enabled — surfacing gray areas before planning ``` +If `$RESEARCH_MODE` only: +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► QUICK TASK (RESEARCH) +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +◆ Research phase enabled — investigating approaches before planning +``` + If `$FULL_MODE` only: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ @@ -70,9 +118,13 @@ If `$FULL_MODE` only: ```bash INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init quick "$DESCRIPTION") if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +AGENT_SKILLS_PLANNER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-planner 2>/dev/null) +AGENT_SKILLS_EXECUTOR=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-executor 2>/dev/null) +AGENT_SKILLS_CHECKER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-checker 2>/dev/null) +AGENT_SKILLS_VERIFIER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-verifier 2>/dev/null) ``` -Parse JSON for: `planner_model`, `executor_model`, `checker_model`, `verifier_model`, `commit_docs`, `next_num`, `slug`, `date`, `timestamp`, `quick_dir`, `task_dir`, `roadmap_exists`, `planning_exists`. +Parse JSON for: `planner_model`, `executor_model`, `checker_model`, `verifier_model`, `commit_docs`, `branch_name`, `quick_id`, `slug`, `date`, `timestamp`, `quick_dir`, `task_dir`, `roadmap_exists`, `planning_exists`. **If `roadmap_exists` is false:** Error — Quick mode requires an active project with ROADMAP.md. Run `/gsd-new-project` first. @@ -80,6 +132,20 @@ Quick tasks can run mid-phase - validation only checks ROADMAP.md exists, not ph --- +**Step 2.5: Handle quick-task branching** + +**If `branch_name` is empty/null:** Skip and continue on the current branch. + +**If `branch_name` is set:** Check out the quick-task branch before any planning commits: + +```bash +git checkout -b "$branch_name" 2>/dev/null || git checkout "$branch_name" +``` + +All quick-task commits for this run stay on that branch. User handles merge/rebase afterward. + +--- + **Step 3: Create task directory** ```bash @@ -93,13 +159,13 @@ mkdir -p "${task_dir}" Create the directory for this quick task: ```bash -QUICK_DIR=".planning/quick/${next_num}-${slug}" +QUICK_DIR=".planning/quick/${quick_id}-${slug}" mkdir -p "$QUICK_DIR" ``` Report to user: ``` -Creating quick task ${next_num}: ${DESCRIPTION} +Creating quick task ${quick_id}: ${DESCRIPTION} Directory: ${QUICK_DIR} ``` @@ -180,10 +246,10 @@ Collect all decisions into `$DECISIONS`. **4.5d. write CONTEXT.md** -write `${QUICK_DIR}/${next_num}-CONTEXT.md` using the standard context template structure: +write `${QUICK_DIR}/${quick_id}-CONTEXT.md` using the standard context template structure: ```markdown -# Quick task ${next_num}: ${DESCRIPTION} - Context +# Quick task ${quick_id}: ${DESCRIPTION} - Context **Gathered:** ${date} **Status:** Ready for planning @@ -217,11 +283,85 @@ ${any_specific_references_or_examples_from_discussion} [If none: "No specific requirements — open to standard approaches"] + + +## Canonical References + +${any_specs_adrs_or_docs_referenced_during_discussion} + +[If none: "No external specs — requirements fully captured in decisions above"] + + ``` -Note: Quick task CONTEXT.md omits `` and `` sections (no codebase scouting, no phase scope to defer to). Keep it lean. +Note: Quick task CONTEXT.md omits `` and `` sections (no codebase scouting, no phase scope to defer to). Keep it lean. The `` section is included when external docs were referenced — omit it only if no external docs apply. -Report: `Context captured: ${QUICK_DIR}/${next_num}-CONTEXT.md` +Report: `Context captured: ${QUICK_DIR}/${quick_id}-CONTEXT.md` + +--- + +**Step 4.75: Research phase (only when `$RESEARCH_MODE`)** + +Skip this step entirely if NOT `$RESEARCH_MODE`. + +Display banner: +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► RESEARCHING QUICK TASK +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +◆ Investigating approaches for: ${DESCRIPTION} +``` + +Spawn a single focused researcher (not 4 parallel researchers like full phases — quick tasks need targeted research, not broad domain surveys): + +``` +task( + prompt=" + + +**Mode:** quick-task +**task:** ${DESCRIPTION} +**Output:** ${QUICK_DIR}/${quick_id}-RESEARCH.md + + +- .planning/STATE.md (Project state — what's already built) +- .planning/PROJECT.md (Project context) +- ./AGENTS.md (if exists — project-specific guidelines) +${DISCUSS_MODE ? '- ' + QUICK_DIR + '/' + quick_id + '-CONTEXT.md (User decisions — research should align with these)' : ''} + + +${AGENT_SKILLS_PLANNER} + + + + +This is a quick task, not a full phase. Research should be concise and targeted: +1. Best libraries/patterns for this specific task +2. Common pitfalls and how to avoid them +3. Integration points with existing codebase +4. Any constraints or gotchas worth knowing before planning + +Do NOT produce a full domain survey. Target 1-2 pages of actionable findings. + + + +write research to: ${QUICK_DIR}/${quick_id}-RESEARCH.md +Use standard research format but keep it lean — skip sections that don't apply. +Return: ## RESEARCH COMPLETE with file path + +", + subagent_type="gsd-phase-researcher", + model="{planner_model}", + description="Research: ${DESCRIPTION}" +) +``` + +After researcher returns: +1. Verify research exists at `${QUICK_DIR}/${quick_id}-RESEARCH.md` +2. Report: "Research complete: ${QUICK_DIR}/${quick_id}-RESEARCH.md" + +If research file not found, warn but continue: "Research agent did not produce output — proceeding to planning without research." --- @@ -243,9 +383,12 @@ task( - .planning/STATE.md (Project State) - ./AGENTS.md (if exists — follow project-specific guidelines) -${DISCUSS_MODE ? '- ' + QUICK_DIR + '/' + next_num + '-CONTEXT.md (User decisions — locked, do not revisit)' : ''} +${DISCUSS_MODE ? '- ' + QUICK_DIR + '/' + quick_id + '-CONTEXT.md (User decisions — locked, do not revisit)' : ''} +${RESEARCH_MODE ? '- ' + QUICK_DIR + '/' + quick_id + '-RESEARCH.md (Research findings — use to inform implementation choices)' : ''} +${AGENT_SKILLS_PLANNER} + **Project skills:** Check .OpenCode/skills/ or .agents/skills/ directory (if either exists) — read SKILL.md files, plans should account for project skill rules @@ -253,14 +396,14 @@ ${DISCUSS_MODE ? '- ' + QUICK_DIR + '/' + next_num + '-CONTEXT.md (User decision - Create a SINGLE plan with 1-3 focused tasks - Quick tasks should be atomic and self-contained -- No research phase +${RESEARCH_MODE ? '- Research findings are available — use them to inform library/pattern choices' : '- No research phase'} ${FULL_MODE ? '- Target ~40% context usage (structured for verification)' : '- Target ~30% context usage (simple, focused)'} ${FULL_MODE ? '- MUST generate `must_haves` in plan frontmatter (truths, artifacts, key_links)' : ''} ${FULL_MODE ? '- Each task MUST have `files`, `action`, `verify`, `done` fields' : ''} -write plan to: ${QUICK_DIR}/${next_num}-PLAN.md +write plan to: ${QUICK_DIR}/${quick_id}-PLAN.md Return: ## PLANNING COMPLETE with plan path ", @@ -271,11 +414,11 @@ Return: ## PLANNING COMPLETE with plan path ``` After planner returns: -1. Verify plan exists at `${QUICK_DIR}/${next_num}-PLAN.md` +1. Verify plan exists at `${QUICK_DIR}/${quick_id}-PLAN.md` 2. Extract plan count (typically 1 for quick tasks) -3. Report: "Plan created: ${QUICK_DIR}/${next_num}-PLAN.md" +3. Report: "Plan created: ${QUICK_DIR}/${quick_id}-PLAN.md" -If plan not found, error: "Planner failed to create ${next_num}-PLAN.md" +If plan not found, error: "Planner failed to create ${quick_id}-PLAN.md" --- @@ -300,9 +443,11 @@ Checker prompt: **task Description:** ${DESCRIPTION} -- ${QUICK_DIR}/${next_num}-PLAN.md (Plan to verify) +- ${QUICK_DIR}/${quick_id}-PLAN.md (Plan to verify) +${AGENT_SKILLS_CHECKER} + **Scope:** This is a quick task, not a full phase. Skip checks that require a ROADMAP phase goal. @@ -352,9 +497,11 @@ Revision prompt: **Mode:** quick-full (revision) -- ${QUICK_DIR}/${next_num}-PLAN.md (Existing plan) +- ${QUICK_DIR}/${quick_id}-PLAN.md (Existing plan) +${AGENT_SKILLS_PLANNER} + **Checker issues:** ${structured_issues_from_checker} @@ -392,36 +539,39 @@ Spawn gsd-executor with plan reference: ``` task( prompt=" -Execute quick task ${next_num}. +Execute quick task ${quick_id}. -- ${QUICK_DIR}/${next_num}-PLAN.md (Plan) +- ${QUICK_DIR}/${quick_id}-PLAN.md (Plan) - .planning/STATE.md (Project state) - ./AGENTS.md (Project instructions, if exists) - .OpenCode/skills/ or .agents/skills/ (Project skills, if either exists — list skills, read SKILL.md for each, follow relevant rules during implementation) +${AGENT_SKILLS_EXECUTOR} + - Execute all tasks in the plan - Commit each task atomically -- Create summary at: ${QUICK_DIR}/${next_num}-SUMMARY.md +- Create summary at: ${QUICK_DIR}/${quick_id}-SUMMARY.md - Do NOT update ROADMAP.md (quick tasks are separate from planned phases) ", subagent_type="gsd-executor", model="{executor_model}", + isolation="worktree", description="Execute: ${DESCRIPTION}" ) ``` After executor returns: -1. Verify summary exists at `${QUICK_DIR}/${next_num}-SUMMARY.md` +1. Verify summary exists at `${QUICK_DIR}/${quick_id}-SUMMARY.md` 2. Extract commit hash from executor output 3. Report completion status **Known OpenCode bug (classifyHandoffIfNeeded):** If executor reports "failed" with error `classifyHandoffIfNeeded is not defined`, this is a OpenCode runtime bug — not a real failure. Check if summary file exists and git log shows commits. If so, treat as successful. -If summary not found, error: "Executor failed to create ${next_num}-SUMMARY.md" +If summary not found, error: "Executor failed to create ${quick_id}-SUMMARY.md" Note: For quick tasks producing multiple plans (rare), spawn executors in parallel waves per execute-phase patterns. @@ -447,10 +597,12 @@ task directory: ${QUICK_DIR} task goal: ${DESCRIPTION} -- ${QUICK_DIR}/${next_num}-PLAN.md (Plan) +- ${QUICK_DIR}/${quick_id}-PLAN.md (Plan) -Check must_haves against actual codebase. Create VERIFICATION.md at ${QUICK_DIR}/${next_num}-VERIFICATION.md.", +${AGENT_SKILLS_VERIFIER} + +Check must_haves against actual codebase. Create VERIFICATION.md at ${QUICK_DIR}/${quick_id}-VERIFICATION.md.", subagent_type="gsd-verifier", model="{verifier_model}", description="Verify: ${DESCRIPTION}" @@ -459,7 +611,7 @@ Check must_haves against actual codebase. Create VERIFICATION.md at ${QUICK_DIR} read verification status: ```bash -grep "^status:" "${QUICK_DIR}/${next_num}-VERIFICATION.md" | cut -d: -f2 | tr -d ' ' +grep "^status:" "${QUICK_DIR}/${quick_id}-VERIFICATION.md" | cut -d: -f2 | tr -d ' ' ``` Store as `$VERIFICATION_STATUS`. @@ -508,19 +660,19 @@ Use `date` from init: **If `$FULL_MODE` (or table has Status column):** ```markdown -| ${next_num} | ${DESCRIPTION} | ${date} | ${commit_hash} | ${VERIFICATION_STATUS} | [${next_num}-${slug}](./quick/${next_num}-${slug}/) | +| ${quick_id} | ${DESCRIPTION} | ${date} | ${commit_hash} | ${VERIFICATION_STATUS} | [${quick_id}-${slug}](./quick/${quick_id}-${slug}/) | ``` **If NOT `$FULL_MODE` (and table has no Status column):** ```markdown -| ${next_num} | ${DESCRIPTION} | ${date} | ${commit_hash} | [${next_num}-${slug}](./quick/${next_num}-${slug}/) | +| ${quick_id} | ${DESCRIPTION} | ${date} | ${commit_hash} | [${quick_id}-${slug}](./quick/${quick_id}-${slug}/) | ``` **7d. Update "Last activity" line:** Use `date` from init: ``` -Last activity: ${date} - Completed quick task ${next_num}: ${DESCRIPTION} +Last activity: ${date} - Completed quick task ${quick_id}: ${DESCRIPTION} ``` Use edit tool to make these changes atomically @@ -532,14 +684,15 @@ Use edit tool to make these changes atomically Stage and commit quick task artifacts: Build file list: -- `${QUICK_DIR}/${next_num}-PLAN.md` -- `${QUICK_DIR}/${next_num}-SUMMARY.md` +- `${QUICK_DIR}/${quick_id}-PLAN.md` +- `${QUICK_DIR}/${quick_id}-SUMMARY.md` - `.planning/STATE.md` -- If `$DISCUSS_MODE` and context file exists: `${QUICK_DIR}/${next_num}-CONTEXT.md` -- If `$FULL_MODE` and verification file exists: `${QUICK_DIR}/${next_num}-VERIFICATION.md` +- If `$DISCUSS_MODE` and context file exists: `${QUICK_DIR}/${quick_id}-CONTEXT.md` +- If `$RESEARCH_MODE` and research file exists: `${QUICK_DIR}/${quick_id}-RESEARCH.md` +- If `$FULL_MODE` and verification file exists: `${QUICK_DIR}/${quick_id}-VERIFICATION.md` ```bash -node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs(quick-${next_num}): ${DESCRIPTION}" --files ${file_list} +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs(quick-${quick_id}): ${DESCRIPTION}" --files ${file_list} ``` Get final commit hash: @@ -555,15 +708,16 @@ Display completion output: GSD > QUICK TASK COMPLETE (FULL MODE) -Quick task ${next_num}: ${DESCRIPTION} +Quick task ${quick_id}: ${DESCRIPTION} -Summary: ${QUICK_DIR}/${next_num}-SUMMARY.md -Verification: ${QUICK_DIR}/${next_num}-VERIFICATION.md (${VERIFICATION_STATUS}) +${RESEARCH_MODE ? 'Research: ' + QUICK_DIR + '/' + quick_id + '-RESEARCH.md' : ''} +Summary: ${QUICK_DIR}/${quick_id}-SUMMARY.md +Verification: ${QUICK_DIR}/${quick_id}-VERIFICATION.md (${VERIFICATION_STATUS}) Commit: ${commit_hash} --- -Ready for next task: /gsd-quick +Ready for next task: /gsd-quick ${GSD_WS} ``` **If NOT `$FULL_MODE`:** @@ -572,14 +726,15 @@ Ready for next task: /gsd-quick GSD > QUICK TASK COMPLETE -Quick task ${next_num}: ${DESCRIPTION} +Quick task ${quick_id}: ${DESCRIPTION} -Summary: ${QUICK_DIR}/${next_num}-SUMMARY.md +${RESEARCH_MODE ? 'Research: ' + QUICK_DIR + '/' + quick_id + '-RESEARCH.md' : ''} +Summary: ${QUICK_DIR}/${quick_id}-SUMMARY.md Commit: ${commit_hash} --- -Ready for next task: /gsd-quick +Ready for next task: /gsd-quick ${GSD_WS} ``` @@ -587,15 +742,16 @@ Ready for next task: /gsd-quick - [ ] ROADMAP.md validation passes - [ ] User provides task description -- [ ] `--full` and `--discuss` flags parsed from arguments when present +- [ ] `--full`, `--discuss`, and `--research` flags parsed from arguments when present - [ ] Slug generated (lowercase, hyphens, max 40 chars) -- [ ] Next number calculated (001, 002, 003...) -- [ ] Directory created at `.planning/quick/NNN-slug/` -- [ ] (--discuss) Gray areas identified and presented, decisions captured in `${next_num}-CONTEXT.md` -- [ ] `${next_num}-PLAN.md` created by planner (honors CONTEXT.md decisions when --discuss) +- [ ] Quick ID generated (YYMMDD-xxx format, 2s Base36 precision) +- [ ] Directory created at `.planning/quick/YYMMDD-xxx-slug/` +- [ ] (--discuss) Gray areas identified and presented, decisions captured in `${quick_id}-CONTEXT.md` +- [ ] (--research) Research agent spawned, `${quick_id}-RESEARCH.md` created +- [ ] `${quick_id}-PLAN.md` created by planner (honors CONTEXT.md decisions when --discuss, uses RESEARCH.md findings when --research) - [ ] (--full) Plan checker validates plan, revision loop capped at 2 -- [ ] `${next_num}-SUMMARY.md` created by executor -- [ ] (--full) `${next_num}-VERIFICATION.md` created by verifier +- [ ] `${quick_id}-SUMMARY.md` created by executor +- [ ] (--full) `${quick_id}-VERIFICATION.md` created by verifier - [ ] STATE.md updated with quick task row (Status column when --full) - [ ] Artifacts committed diff --git a/gsd-opencode/get-shit-done/workflows/remove-phase.md b/gsd-opencode/get-shit-done/workflows/remove-phase.md index bd4bfaa..2810c16 100644 --- a/gsd-opencode/get-shit-done/workflows/remove-phase.md +++ b/gsd-opencode/get-shit-done/workflows/remove-phase.md @@ -1,6 +1,6 @@ - + Remove an unstarted future phase from the project roadmap, delete its directory, renumber all subsequent phases to maintain a clean linear sequence, and commit the change. The git commit serves as the historical record of removal. - + read all files referenced by the invoking prompt's execution_context before starting. diff --git a/gsd-opencode/get-shit-done/workflows/remove-workspace.md b/gsd-opencode/get-shit-done/workflows/remove-workspace.md new file mode 100644 index 0000000..7569960 --- /dev/null +++ b/gsd-opencode/get-shit-done/workflows/remove-workspace.md @@ -0,0 +1,90 @@ + +Remove a GSD workspace, cleaning up git worktrees and deleting the workspace directory. + + + +read all files referenced by the invoking prompt's execution_context before starting. + + + + +## 1. Setup + +Extract workspace name from $ARGUMENTS. + +```bash +INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init remove-workspace "$WORKSPACE_NAME") +if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +``` + +Parse JSON for: `workspace_name`, `workspace_path`, `has_manifest`, `strategy`, `repos`, `repo_count`, `dirty_repos`, `has_dirty_repos`. + +**If no workspace name provided:** + +First run `/gsd-list-workspaces` to show available workspaces, then ask: + +Use question: +- header: "Remove Workspace" +- question: "Which workspace do you want to remove?" +- requireAnswer: true + +Re-run init with the provided name. + +## 2. Safety Checks + +**If `has_dirty_repos` is true:** + +``` +Cannot remove workspace "$WORKSPACE_NAME" — the following repos have uncommitted changes: + + - repo1 + - repo2 + +Commit or stash changes in these repos before removing the workspace: + cd $WORKSPACE_PATH/repo1 + git stash # or git commit +``` + +Exit. Do NOT proceed. + +## 3. Confirm Removal + +Use question: +- header: "Confirm Removal" +- question: "Remove workspace '$WORKSPACE_NAME' at $WORKSPACE_PATH? This will delete all files in the workspace directory. Type the workspace name to confirm:" +- requireAnswer: true + +**If answer does not match `$WORKSPACE_NAME`:** Exit with "Removal cancelled." + +## 4. Clean Up Worktrees + +**If strategy is `worktree`:** + +For each repo in the workspace: + +```bash +cd "$SOURCE_REPO_PATH" +git worktree remove "$WORKSPACE_PATH/$REPO_NAME" 2>&1 || true +``` + +If `git worktree remove` fails, warn but continue: +``` +Warning: Could not remove worktree for $REPO_NAME — source repo may have been moved or deleted. +``` + +## 5. Delete Workspace Directory + +```bash +rm -rf "$WORKSPACE_PATH" +``` + +## 6. Report + +``` +Workspace "$WORKSPACE_NAME" removed. + + Path: $WORKSPACE_PATH (deleted) + Repos: $REPO_COUNT worktrees cleaned up +``` + + diff --git a/gsd-opencode/get-shit-done/workflows/research-phase.md b/gsd-opencode/get-shit-done/workflows/research-phase.md index 06f1264..bfa3fda 100644 --- a/gsd-opencode/get-shit-done/workflows/research-phase.md +++ b/gsd-opencode/get-shit-done/workflows/research-phase.md @@ -1,8 +1,13 @@ - + Research how to implement a phase. Spawns gsd-phase-researcher with phase context. Standalone research command. For most workflows, use `/gsd-plan-phase` which integrates research automatically. - + + + +Valid GSD subagent types (use exact names — do not fall back to 'general'): +- gsd-phase-researcher — Researches technical approaches for a phase + @@ -26,7 +31,7 @@ If `found` is false: Error and exit. ## Step 2: Check Existing Research ```bash -ls .planning/phases/${PHASE}-*/RESEARCH.md 2>/dev/null +ls .planning/phases/${PHASE}-*/RESEARCH.md 2>/dev/null || true ``` If exists: Offer update/view/skip options. @@ -37,6 +42,7 @@ If exists: Offer update/view/skip options. INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE}") if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi # Extract: phase_dir, padded_phase, phase_number, state_path, requirements_path, context_path +AGENT_SKILLS_RESEARCHER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-researcher 2>/dev/null) ``` ## Step 4: Spawn Researcher @@ -53,6 +59,8 @@ Research implementation approach for Phase {phase}: {name} - {state_path} (Project decisions and history) +${AGENT_SKILLS_RESEARCHER} + Phase description: {description} diff --git a/gsd-opencode/get-shit-done/workflows/resume-project.md b/gsd-opencode/get-shit-done/workflows/resume-project.md index cb08f81..e1bc7ac 100644 --- a/gsd-opencode/get-shit-done/workflows/resume-project.md +++ b/gsd-opencode/get-shit-done/workflows/resume-project.md @@ -6,9 +6,9 @@ Use this workflow when: - User returns after time away from project - + Instantly restore full project context so "Where were we?" has an immediate, complete answer. - + @$HOME/.config/opencode/get-shit-done/references/continuation-format.md @@ -63,14 +63,18 @@ cat .planning/PROJECT.md Look for incomplete work that needs attention: ```bash +# Check for structured handoff (preferred — machine-readable) +cat .planning/HANDOFF.json 2>/dev/null || true + # Check for continue-here files (mid-plan resumption) -ls .planning/phases/*/.continue-here*.md 2>/dev/null +ls .planning/phases/*/.continue-here*.md 2>/dev/null || true # Check for plans without summaries (incomplete execution) for plan in .planning/phases/*/*-PLAN.md; do + [ -e "$plan" ] || continue summary="${plan/PLAN/SUMMARY}" [ ! -f "$summary" ] && echo "Incomplete: $plan" -done 2>/dev/null +done 2>/dev/null || true # Check for interrupted agents (use has_interrupted_agent and interrupted_agent_id from init) if [ "$has_interrupted_agent" = "true" ]; then @@ -78,7 +82,18 @@ if [ "$has_interrupted_agent" = "true" ]; then fi ``` -**If .continue-here file exists:** +**If HANDOFF.json exists:** + +- This is the primary resumption source — structured data from `/gsd-pause-work` +- Parse `status`, `phase`, `plan`, `task`, `total_tasks`, `next_action` +- Check `blockers` and `human_actions_pending` — surface these immediately +- Check `completed_tasks` for `in_progress` items — these need attention first +- Validate `uncommitted_files` against `git status` — flag divergence +- Use `context_notes` to restore mental model +- Flag: "Found structured handoff — resuming from task {task}/{total_tasks}" +- **After successful resumption, delete HANDOFF.json** (it's a one-shot artifact) + +**If .continue-here file exists (fallback):** - This is a mid-plan resumption point - read the file for specific resumption context @@ -145,8 +160,12 @@ Based on project state, determine the most logical next action: → Primary: Resume interrupted agent (task tool with resume parameter) → Option: Start fresh (abandon agent work) +**If HANDOFF.json exists:** +→ Primary: Resume from structured handoff (highest priority — specific task/blocker context) +→ Option: Discard handoff and reassess from files + **If .continue-here file exists:** -→ Primary: Resume from checkpoint +→ Fallback: Resume from checkpoint → Option: Start fresh on current plan **If incomplete plan (PLAN without SUMMARY):** @@ -154,7 +173,7 @@ Based on project state, determine the most logical next action: → Option: Abandon and move on **If phase in progress, all plans complete:** -→ Primary: Transition to next phase +→ Primary: Advance to next phase (via internal transition workflow) → Option: Review completed work **If phase ready to plan:** @@ -181,11 +200,11 @@ What would you like to do? [Primary action based on state - e.g.:] 1. Resume interrupted agent [if interrupted agent found] OR -1. Execute phase (/gsd-execute-phase {phase}) +1. Execute phase (/gsd-execute-phase {phase} ${GSD_WS}) OR -1. Discuss Phase 3 context (/gsd-discuss-phase 3) [if CONTEXT.md missing] +1. Discuss Phase 3 context (/gsd-discuss-phase 3 ${GSD_WS}) [if CONTEXT.md missing] OR -1. Plan Phase 3 (/gsd-plan-phase 3) [if CONTEXT.md exists or discuss option declined] +1. Plan Phase 3 (/gsd-plan-phase 3 ${GSD_WS}) [if CONTEXT.md exists or discuss option declined] [Secondary options:] 2. Review current phase status @@ -197,7 +216,7 @@ What would you like to do? **Note:** When offering phase planning, check for CONTEXT.md existence first: ```bash -ls .planning/phases/XX-name/*-CONTEXT.md 2>/dev/null +ls .planning/phases/XX-name/*-CONTEXT.md 2>/dev/null || true ``` If missing, suggest discuss-phase before plan. If exists, offer plan directly. @@ -216,7 +235,7 @@ Based on user selection, route to appropriate workflow: **{phase}-{plan}: [Plan Name]** — [objective from PLAN.md] - `/gsd-execute-phase {phase}` + `/gsd-execute-phase {phase} ${GSD_WS}` *`/new` first → fresh context window* @@ -230,19 +249,19 @@ Based on user selection, route to appropriate workflow: **Phase [N]: [Name]** — [Goal from ROADMAP.md] - `/gsd-plan-phase [phase-number]` + `/gsd-plan-phase [phase-number] ${GSD_WS}` *`/new` first → fresh context window* --- **Also available:** - - `/gsd-discuss-phase [N]` — gather context first - - `/gsd-research-phase [N]` — investigate unknowns + - `/gsd-discuss-phase [N] ${GSD_WS}` — gather context first + - `/gsd-research-phase [N] ${GSD_WS}` — investigate unknowns --- ``` -- **Transition** → ./transition.md +- **Advance to next phase** → ./transition.md (internal workflow, invoked inline — NOT a user command) - **Check todos** → read .planning/todos/pending/, present summary - **Review alignment** → read PROJECT.md, compare to current state - **Something else** → Ask what they need diff --git a/gsd-opencode/get-shit-done/workflows/review.md b/gsd-opencode/get-shit-done/workflows/review.md new file mode 100644 index 0000000..35dad12 --- /dev/null +++ b/gsd-opencode/get-shit-done/workflows/review.md @@ -0,0 +1,228 @@ + +Cross-AI peer review — invoke external AI CLIs to independently review phase plans. +Each CLI gets the same prompt (PROJECT.md context, phase plans, requirements) and +produces structured feedback. Results are combined into REVIEWS.md for the planner +to incorporate via --reviews flag. + +This implements adversarial review: different AI models catch different blind spots. +A plan that survives review from 2-3 independent AI systems is more robust. + + + + + +Check which AI CLIs are available on the system: + +```bash +# Check each CLI +command -v gemini >/dev/null 2>&1 && echo "gemini:available" || echo "gemini:missing" +command -v OpenCode >/dev/null 2>&1 && echo "OpenCode:available" || echo "OpenCode:missing" +command -v codex >/dev/null 2>&1 && echo "codex:available" || echo "codex:missing" +``` + +Parse flags from `$ARGUMENTS`: +- `--gemini` → include Gemini +- `--OpenCode` → include OpenCode +- `--codex` → include Codex +- `--all` → include all available +- No flags → include all available + +If no CLIs are available: +``` +No external AI CLIs found. Install at least one: +- gemini: https://github.com/google-gemini/gemini-cli +- codex: https://github.com/openai/codex +- OpenCode: https://github.com/anthropics/OpenCode-code + +Then run /gsd-review again. +``` +Exit. + +If only one CLI is the current runtime (e.g. running inside OpenCode), skip it for the review +to ensure independence. At least one DIFFERENT CLI must be available. + + + +Collect phase artifacts for the review prompt: + +```bash +INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE_ARG}") +if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +``` + +read from init: `phase_dir`, `phase_number`, `padded_phase`. + +Then read: +1. `.planning/PROJECT.md` (first 80 lines — project context) +2. Phase section from `.planning/ROADMAP.md` +3. All `*-PLAN.md` files in the phase directory +4. `*-CONTEXT.md` if present (user decisions) +5. `*-RESEARCH.md` if present (domain research) +6. `.planning/REQUIREMENTS.md` (requirements this phase addresses) + + + +Build a structured review prompt: + +```markdown +# Cross-AI Plan Review Request + +You are reviewing implementation plans for a software project phase. +Provide structured feedback on plan quality, completeness, and risks. + +## Project Context +{first 80 lines of PROJECT.md} + +## Phase {N}: {phase name} +### Roadmap Section +{roadmap phase section} + +### Requirements Addressed +{requirements for this phase} + +### User Decisions (CONTEXT.md) +{context if present} + +### Research Findings +{research if present} + +### Plans to Review +{all PLAN.md contents} + +## Review Instructions + +Analyze each plan and provide: + +1. **Summary** — One-paragraph assessment +2. **Strengths** — What's well-designed (bullet points) +3. **Concerns** — Potential issues, gaps, risks (bullet points with severity: HIGH/MEDIUM/LOW) +4. **Suggestions** — Specific improvements (bullet points) +5. **Risk Assessment** — Overall risk level (LOW/MEDIUM/HIGH) with justification + +Focus on: +- Missing edge cases or error handling +- Dependency ordering issues +- Scope creep or over-engineering +- Security considerations +- Performance implications +- Whether the plans actually achieve the phase goals + +Output your review in markdown format. +``` + +write to a temp file: `/tmp/gsd-review-prompt-{phase}.md` + + + +For each selected CLI, invoke in sequence (not parallel — avoid rate limits): + +**Gemini:** +```bash +gemini -p "$(cat /tmp/gsd-review-prompt-{phase}.md)" 2>/dev/null > /tmp/gsd-review-gemini-{phase}.md +``` + +**OpenCode (separate session):** +```bash +OpenCode -p "$(cat /tmp/gsd-review-prompt-{phase}.md)" --no-input 2>/dev/null > /tmp/gsd-review-OpenCode-{phase}.md +``` + +**Codex:** +```bash +codex exec --skip-git-repo-check "$(cat /tmp/gsd-review-prompt-{phase}.md)" 2>/dev/null > /tmp/gsd-review-codex-{phase}.md +``` + +If a CLI fails, log the error and continue with remaining CLIs. + +Display progress: +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► CROSS-AI REVIEW — Phase {N} +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +◆ Reviewing with {CLI}... done ✓ +◆ Reviewing with {CLI}... done ✓ +``` + + + +Combine all review responses into `{phase_dir}/{padded_phase}-REVIEWS.md`: + +```markdown +--- +phase: {N} +reviewers: [gemini, OpenCode, codex] +reviewed_at: {ISO timestamp} +plans_reviewed: [{list of PLAN.md files}] +--- + +# Cross-AI Plan Review — Phase {N} + +## Gemini Review + +{gemini review content} + +--- + +## OpenCode Review + +{OpenCode review content} + +--- + +## Codex Review + +{codex review content} + +--- + +## Consensus Summary + +{synthesize common concerns across all reviewers} + +### Agreed Strengths +{strengths mentioned by 2+ reviewers} + +### Agreed Concerns +{concerns raised by 2+ reviewers — highest priority} + +### Divergent Views +{where reviewers disagreed — worth investigating} +``` + +Commit: +```bash +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: cross-AI review for phase {N}" --files {phase_dir}/{padded_phase}-REVIEWS.md +``` + + + +Display summary: + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► REVIEW COMPLETE +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Phase {N} reviewed by {count} AI systems. + +Consensus concerns: +{top 3 shared concerns} + +Full review: {padded_phase}-REVIEWS.md + +To incorporate feedback into planning: + /gsd-plan-phase {N} --reviews +``` + +Clean up temp files. + + + + + +- [ ] At least one external CLI invoked successfully +- [ ] REVIEWS.md written with structured feedback +- [ ] Consensus summary synthesized from multiple reviewers +- [ ] Temp files cleaned up +- [ ] User knows how to use feedback (/gsd-plan-phase --reviews) + diff --git a/gsd-opencode/get-shit-done/workflows/session-report.md b/gsd-opencode/get-shit-done/workflows/session-report.md new file mode 100644 index 0000000..626216d --- /dev/null +++ b/gsd-opencode/get-shit-done/workflows/session-report.md @@ -0,0 +1,146 @@ + +Generate a post-session summary document capturing work performed, outcomes achieved, and estimated resource usage. Writes SESSION_REPORT.md to .planning/reports/ for human review and stakeholder sharing. + + + +read all files referenced by the invoking prompt's execution_context before starting. + + + + + +Collect session data from available sources: + +1. **STATE.md** — current phase, milestone, progress, blockers, decisions +2. **Git log** — commits made during this session (last 24h or since last report) +3. **Plan/Summary files** — plans executed, summaries written +4. **ROADMAP.md** — milestone context and phase goals + +```bash +# Get recent commits (last 24 hours) +git log --oneline --since="24 hours ago" --no-merges 2>/dev/null || echo "No recent commits" + +# Count files changed +git diff --stat HEAD~10 HEAD 2>/dev/null | tail -1 || echo "No diff available" +``` + +read `.planning/STATE.md` to get: +- Current milestone and phase +- Progress percentage +- Active blockers +- Recent decisions + +read `.planning/ROADMAP.md` to get milestone name and goals. + +Check for existing reports: +```bash +ls -la .planning/reports/SESSION_REPORT*.md 2>/dev/null || echo "No previous reports" +``` + + + +Estimate token usage from observable signals: + +- Count of tool calls is not directly available, so estimate from git activity and file operations +- Note: This is an **estimate** — exact token counts require API-level instrumentation not available to hooks + +Estimation heuristics: +- Each commit ≈ 1 plan cycle (research + plan + execute + verify) +- Each plan file ≈ 2,000-5,000 tokens of agent context +- Each summary file ≈ 1,000-2,000 tokens generated +- Subagent spawns multiply by ~1.5x per agent type used + + + +Create the report directory and file: + +```bash +mkdir -p .planning/reports +``` + +write `.planning/reports/SESSION_REPORT.md` (or `.planning/reports/YYYYMMDD-session-report.md` if previous reports exist): + +```markdown +# GSD Session Report + +**Generated:** [timestamp] +**Project:** [from PROJECT.md title or directory name] +**Milestone:** [N] — [milestone name from ROADMAP.md] + +--- + +## Session Summary + +**Duration:** [estimated from first to last commit timestamp, or "Single session"] +**Phase Progress:** [from STATE.md] +**Plans Executed:** [count of summaries written this session] +**Commits Made:** [count from git log] + +## Work Performed + +### Phases Touched +[List phases worked on with brief description of what was done] + +### Key Outcomes +[Bullet list of concrete deliverables: files created, features implemented, bugs fixed] + +### Decisions Made +[From STATE.md decisions table, if any were added this session] + +## Files Changed + +[Summary of files modified, created, deleted — from git diff stat] + +## Blockers & Open Items + +[Active blockers from STATE.md] +[Any TODO items created during session] + +## Estimated Resource Usage + +| Metric | Estimate | +|--------|----------| +| Commits | [N] | +| Files changed | [N] | +| Plans executed | [N] | +| Subagents spawned | [estimated] | + +> **Note:** Token and cost estimates require API-level instrumentation. +> These metrics reflect observable session activity only. + +--- + +*Generated by `/gsd-session-report`* +``` + + + +Show the user: + +``` +## Session Report Generated + +📄 `.planning/reports/[filename].md` + +### Highlights +- **Commits:** [N] +- **Files changed:** [N] +- **Phase progress:** [X]% +- **Plans executed:** [N] +``` + +If this is the first report, mention: +``` +💡 Run `/gsd-session-report` at the end of each session to build a history of project activity. +``` + + + + + +- [ ] Session data gathered from STATE.md, git log, and plan files +- [ ] Report written to .planning/reports/ +- [ ] Report includes work summary, outcomes, and file changes +- [ ] Filename includes date to prevent overwrites +- [ ] Result summary displayed to user + diff --git a/gsd-opencode/get-shit-done/workflows/set-profile.md b/gsd-opencode/get-shit-done/workflows/set-profile.md index ba94b93..4194e27 100644 --- a/gsd-opencode/get-shit-done/workflows/set-profile.md +++ b/gsd-opencode/get-shit-done/workflows/set-profile.md @@ -1,6 +1,6 @@ - + Switch the model profile used by GSD agents. Controls which OpenCode model each agent uses, balancing quality vs token spend. - + read all files referenced by the invoking prompt's execution_context before starting. diff --git a/gsd-opencode/get-shit-done/workflows/settings.md b/gsd-opencode/get-shit-done/workflows/settings.md index 2068248..cb51a8c 100644 --- a/gsd-opencode/get-shit-done/workflows/settings.md +++ b/gsd-opencode/get-shit-done/workflows/settings.md @@ -1,6 +1,6 @@ - + Interactive configuration of GSD workflow agents (research, plan_check, verifier) and model profile selection via multi-question prompt. Updates .planning/config.json with user preferences. Optionally saves settings as global defaults (~/.gsd/defaults.json) for future projects. - + read all files referenced by the invoking prompt's execution_context before starting. @@ -30,6 +30,8 @@ Parse current values (default to `true` if not present): - `workflow.plan_check` — spawn plan checker during plan-phase - `workflow.verifier` — spawn verifier during execute-phase - `workflow.nyquist_validation` — validation architecture research during plan-phase (default: true if absent) +- `workflow.ui_phase` — generate UI-SPEC.md design contracts for frontend phases (default: true if absent) +- `workflow.ui_safety_gate` — prompt to run /gsd-ui-phase before planning frontend phases (default: true if absent) - `model_profile` — which model each agent uses (default: `simple`) - `git.branching_strategy` — branching approach (default: `"none"`) @@ -45,8 +47,9 @@ question([ multiSelect: false, options: [ { label: "Simple", description: "One model for all agents (not flexible)" }, - { label: "Smart (Recommended)", description: "Two models: one for reseach and planing, other for execution and verification" }, - { label: "Genius (most flexible)", description: "Three models: different for every stage" } + { label: "Smart (Recommended)", description: "Opus for planning, Sonnet for research/execution/verification" }, + { label: "Genius (most flexible)", description: "Three models: different for every stage" }, + { label: "Inherit", description: "Use current session model for all agents (best for OpenRouter, local models, or runtime model switching)" } ] }, { @@ -94,6 +97,26 @@ question([ { label: "No", description: "Skip validation research. Good for rapid prototyping or no-test phases." } ] }, + // Note: Nyquist validation depends on research output. If research is disabled, + // plan-phase automatically skips Nyquist steps (no RESEARCH.md to extract from). + { + question: "Enable UI Phase? (generates UI-SPEC.md design contracts for frontend phases)", + header: "UI Phase", + multiSelect: false, + options: [ + { label: "Yes (Recommended)", description: "Generate UI design contracts before planning frontend phases. Locks spacing, typography, color, and copywriting." }, + { label: "No", description: "Skip UI-SPEC generation. Good for backend-only projects or API phases." } + ] + }, + { + question: "Enable UI Safety Gate? (prompts to run /gsd-ui-phase before planning frontend phases)", + header: "UI Gate", + multiSelect: false, + options: [ + { label: "Yes (Recommended)", description: "plan-phase asks to run /gsd-ui-phase first when frontend indicators detected." }, + { label: "No", description: "No prompt — plan-phase proceeds without UI-SPEC check." } + ] + }, { question: "Git branching strategy?", header: "Branching", @@ -103,6 +126,33 @@ question([ { label: "Per Phase", description: "Create branch for each phase (gsd/phase-{N}-{name})" }, { label: "Per Milestone", description: "Create branch for entire milestone (gsd/{version}-{name})" } ] + }, + { + question: "Enable context window warnings? (injects advisory messages when context is getting full)", + header: "Ctx Warnings", + multiSelect: false, + options: [ + { label: "Yes (Recommended)", description: "Warn when context usage exceeds 65%. Helps avoid losing work." }, + { label: "No", description: "Disable warnings. Allows OpenCode to reach auto-compact naturally. Good for long unattended runs." } + ] + }, + { + question: "Research best practices before asking questions? (web search during new-project and discuss-phase)", + header: "Research Qs", + multiSelect: false, + options: [ + { label: "No (Recommended)", description: "Ask questions directly. Faster, uses fewer tokens." }, + { label: "Yes", description: "Search web for best practices before each question group. More informed questions but uses more tokens." } + ] + }, + { + question: "Skip discuss-phase in autonomous mode? (use ROADMAP phase goals as spec)", + header: "Skip Discuss", + multiSelect: false, + options: [ + { label: "No (Recommended)", description: "Run smart discuss before each phase — surfaces gray areas and captures decisions." }, + { label: "Yes", description: "Skip discuss in /gsd-autonomous — chain directly to plan. Best for backend/pipeline work where phase descriptions are the spec." } + ] } ]) ``` @@ -114,16 +164,27 @@ Merge new settings into existing config.json: ```json { ...existing_config, - "model_profile": "simple" | "smart" | "genius", + "model_profile": "simple" | "smart" | "genius" | "inherit", "workflow": { "research": true/false, "plan_check": true/false, "verifier": true/false, "auto_advance": true/false, - "nyquist_validation": true/false + "nyquist_validation": true/false, + "ui_phase": true/false, + "ui_safety_gate": true/false, + "text_mode": true/false, + "research_before_questions": true/false, + "discuss_mode": "discuss" | "assumptions", + "skip_discuss": true/false }, "git": { - "branching_strategy": "none" | "phase" | "milestone" + "branching_strategy": "none" | "phase" | "milestone", + "quick_branch_template": + }, + "hooks": { + "context_warnings": true/false, + "workflow_guard": true/false } } ``` @@ -163,12 +224,16 @@ write `~/.gsd/defaults.json` with: "commit_docs": , "parallelization": , "branching_strategy": , + "quick_branch_template": , "workflow": { "research": , "plan_check": , "verifier": , "auto_advance": , - "nyquist_validation": + "nyquist_validation": , + "ui_phase": , + "ui_safety_gate": , + "skip_discuss": } } ``` @@ -184,13 +249,17 @@ Display: | Setting | Value | |----------------------|-------| -| Model Profile | {simple/smart/genius} | +| Model Profile | {simple/smart/genius/inherit} | | Plan Researcher | {On/Off} | | Plan Checker | {On/Off} | | Execution Verifier | {On/Off} | | Auto-Advance | {On/Off} | | Nyquist Validation | {On/Off} | +| UI Phase | {On/Off} | +| UI Safety Gate | {On/Off} | | Git Branching | {None/Per Phase/Per Milestone} | +| Skip Discuss | {On/Off} | +| Context Warnings | {On/Off} | | Saved as Defaults | {Yes/No} | These settings apply to future /gsd-plan-phase and /gsd-execute-phase runs. @@ -207,7 +276,7 @@ Quick commands: - [ ] Current config read -- [ ] User presented with 7 settings (profile + 5 workflow toggles + git branching) +- [ ] User presented with 10 settings (profile + 8 workflow toggles + git branching) - [ ] Config updated with model_profile, workflow, and git sections - [ ] User offered to save as global defaults (~/.gsd/defaults.json) - [ ] Changes confirmed to user diff --git a/gsd-opencode/get-shit-done/workflows/ship.md b/gsd-opencode/get-shit-done/workflows/ship.md new file mode 100644 index 0000000..f9da9ba --- /dev/null +++ b/gsd-opencode/get-shit-done/workflows/ship.md @@ -0,0 +1,228 @@ + +Create a pull request from completed phase/milestone work, generate a rich PR body from planning artifacts, optionally run code review, and prepare for merge. Closes the plan → execute → verify → ship loop. + + + +read all files referenced by the invoking prompt's execution_context before starting. + + + + + +Parse arguments and load project state: + +```bash +INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE_ARG}") +if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +``` + +Parse from init JSON: `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `padded_phase`, `commit_docs`. + +Also load config for branching strategy: +```bash +CONFIG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" state load) +``` + +Extract: `branching_strategy`, `branch_name`. + + + +Verify the work is ready to ship: + +1. **Verification passed?** + ```bash + VERIFICATION=$(cat ${PHASE_DIR}/*-VERIFICATION.md 2>/dev/null) + ``` + Check for `status: passed` or `status: human_needed` (with human approval). + If no VERIFICATION.md or status is `gaps_found`: warn and ask user to confirm. + +2. **Clean working tree?** + ```bash + git status --short + ``` + If uncommitted changes exist: ask user to commit or stash first. + +3. **On correct branch?** + ```bash + CURRENT_BRANCH=$(git branch --show-current) + ``` + If on `main`/`master`: warn — should be on a feature branch. + If branching_strategy is `none`: offer to create a branch now. + +4. **Remote configured?** + ```bash + git remote -v | head -2 + ``` + Detect `origin` remote. If no remote: error — can't create PR. + +5. **`gh` CLI available?** + ```bash + which gh && gh auth status 2>&1 + ``` + If `gh` not found or not authenticated: provide setup instructions and exit. + + + +Push the current branch to remote: + +```bash +git push origin ${CURRENT_BRANCH} 2>&1 +``` + +If push fails (e.g., no upstream): set upstream: +```bash +git push --set-upstream origin ${CURRENT_BRANCH} 2>&1 +``` + +Report: "Pushed `{branch}` to origin ({commit_count} commits ahead of main)" + + + +Auto-generate a rich PR body from planning artifacts: + +**1. Title:** +``` +Phase {phase_number}: {phase_name} +``` +Or for milestone: `Milestone {version}: {name}` + +**2. Summary section:** +read ROADMAP.md for phase goal. read VERIFICATION.md for verification status. + +```markdown +## Summary + +**Phase {N}: {Name}** +**Goal:** {goal from ROADMAP.md} +**Status:** Verified ✓ + +{One paragraph synthesized from SUMMARY.md files — what was built} +``` + +**3. Changes section:** +For each SUMMARY.md in the phase directory: +```markdown +## Changes + +### Plan {plan_id}: {plan_name} +{one_liner from SUMMARY.md frontmatter} + +**Key files:** +{key-files.created and key-files.modified from SUMMARY.md frontmatter} +``` + +**4. Requirements section:** +```markdown +## Requirements Addressed + +{REQ-IDs from plan frontmatter, linked to REQUIREMENTS.md descriptions} +``` + +**5. Testing section:** +```markdown +## Verification + +- [x] Automated verification: {pass/fail from VERIFICATION.md} +- {human verification items from VERIFICATION.md, if any} +``` + +**6. Decisions section:** +```markdown +## Key Decisions + +{Decisions from STATE.md accumulated context relevant to this phase} +``` + + + +Create the PR using the generated body: + +```bash +gh pr create \ + --title "Phase ${PHASE_NUMBER}: ${PHASE_NAME}" \ + --body "${PR_BODY}" \ + --base main +``` + +If `--draft` flag was passed: add `--draft`. + +Report: "PR #{number} created: {url}" + + + +Ask if user wants to trigger a code review: + +``` +question: + question: "PR created. Run a code review before merge?" + options: + - label: "Skip review" + description: "PR is ready — merge when CI passes" + - label: "Self-review" + description: "I'll review the diff in the PR myself" + - label: "Request review" + description: "Request review from a teammate" +``` + +**If "Request review":** +```bash +gh pr edit ${PR_NUMBER} --add-reviewer "${REVIEWER}" +``` + +**If "Self-review":** +Report the PR URL and suggest: "Review the diff at {url}/files" + + + +Update STATE.md to reflect the shipping action: + +```bash +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" state update "Last Activity" "$(date +%Y-%m-%d)" +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" state update "Status" "Phase ${PHASE_NUMBER} shipped — PR #${PR_NUMBER}" +``` + +If `commit_docs` is true: +```bash +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs(${padded_phase}): ship phase ${PHASE_NUMBER} — PR #${PR_NUMBER}" --files .planning/STATE.md +``` + + + +``` +─────────────────────────────────────────────────────────────── + +## ✓ Phase {X}: {Name} — Shipped + +PR: #{number} ({url}) +Branch: {branch} → main +Commits: {count} +Verification: ✓ Passed +Requirements: {N} REQ-IDs addressed + +Next steps: +- Review/approve PR +- Merge when CI passes +- /gsd-complete-milestone (if last phase in milestone) +- /gsd-progress (to see what's next) + +─────────────────────────────────────────────────────────────── +``` + + + + + +After shipping: + +- /gsd-complete-milestone — if all phases in milestone are done +- /gsd-progress — see overall project state +- /gsd-execute-phase {next} — continue to next phase + + + +- [ ] Preflight checks passed (verification, clean tree, branch, remote, gh) +- [ ] Branch pushed to remote +- [ ] PR created with rich auto-generated body +- [ ] STATE.md updated with shipping status +- [ ] User knows PR number and next steps + diff --git a/gsd-opencode/get-shit-done/workflows/stats.md b/gsd-opencode/get-shit-done/workflows/stats.md new file mode 100644 index 0000000..3591455 --- /dev/null +++ b/gsd-opencode/get-shit-done/workflows/stats.md @@ -0,0 +1,60 @@ + +Display comprehensive project statistics including phases, plans, requirements, git metrics, and timeline. + + + +read all files referenced by the invoking prompt's execution_context before starting. + + + + + +Gather project statistics: + +```bash +STATS=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" stats json) +if [[ "$STATS" == @file:* ]]; then STATS=$(cat "${STATS#@file:}"); fi +``` + +Extract fields from JSON: `milestone_version`, `milestone_name`, `phases`, `phases_completed`, `phases_total`, `total_plans`, `total_summaries`, `percent`, `plan_percent`, `requirements_total`, `requirements_complete`, `git_commits`, `git_first_commit_date`, `last_activity`. + + + +Present to the user with this format: + +``` +# 📊 Project Statistics — {milestone_version} {milestone_name} + +## Progress +[████████░░] X/Y phases (Z%) + +## Plans +X/Y plans complete (Z%) + +## Phases +| Phase | Name | Plans | Completed | Status | +|-------|------|-------|-----------|--------| +| ... | ... | ... | ... | ... | + +## Requirements +✅ X/Y requirements complete + +## Git +- **Commits:** N +- **Started:** YYYY-MM-DD +- **Last activity:** YYYY-MM-DD + +## Timeline +- **Project age:** N days +``` + +If no `.planning/` directory exists, inform the user to run `/gsd-new-project` first. + + + + + +- [ ] Statistics gathered from project state +- [ ] Results formatted clearly +- [ ] Displayed to user + diff --git a/gsd-opencode/get-shit-done/workflows/transition.md b/gsd-opencode/get-shit-done/workflows/transition.md index 8bc38df..129dd0c 100644 --- a/gsd-opencode/get-shit-done/workflows/transition.md +++ b/gsd-opencode/get-shit-done/workflows/transition.md @@ -1,3 +1,19 @@ + + +**This is an INTERNAL workflow — NOT a user-facing command.** + +There is no `/gsd-transition` command. This workflow is invoked automatically by +`execute-phase` during auto-advance, or inline by the orchestrator after phase +verification. Users should never be told to run `/gsd-transition`. + +**Valid user commands for phase progression:** +- `/gsd-discuss-phase {N}` — discuss a phase before planning +- `/gsd-plan-phase {N}` — plan a phase +- `/gsd-execute-phase {N}` — execute a phase +- `/gsd-progress` — see roadmap progress + + + **read these files NOW:** @@ -10,13 +26,13 @@ - + Mark current phase complete and advance to next. This is the natural point where progress tracking and PROJECT.md evolution happen. "Planning next phase" = "current phase is done" - + @@ -25,8 +41,8 @@ Mark current phase complete and advance to next. This is the natural point where Before transition, read project state: ```bash -cat .planning/STATE.md 2>/dev/null -cat .planning/PROJECT.md 2>/dev/null +cat .planning/STATE.md 2>/dev/null || true +cat .planning/PROJECT.md 2>/dev/null || true ``` Parse current position to verify we're transitioning the right phase. @@ -39,8 +55,8 @@ Note accumulated context that may need updating after transition. Check current phase has all plan summaries: ```bash -ls .planning/phases/XX-current/*-PLAN.md 2>/dev/null | sort -ls .planning/phases/XX-current/*-SUMMARY.md 2>/dev/null | sort +(ls .planning/phases/XX-current/*-PLAN.md 2>/dev/null || true) | sort +(ls .planning/phases/XX-current/*-SUMMARY.md 2>/dev/null || true) | sort ``` **Verification logic:** @@ -53,11 +69,35 @@ ls .planning/phases/XX-current/*-SUMMARY.md 2>/dev/null | sort ```bash -cat .planning/config.json 2>/dev/null +cat .planning/config.json 2>/dev/null || true ``` +**Check for verification debt in this phase:** + +```bash +# Count outstanding items in current phase +OUTSTANDING="" +for f in .planning/phases/XX-current/*-UAT.md .planning/phases/XX-current/*-VERIFICATION.md; do + [ -f "$f" ] || continue + grep -q "result: pending\|result: blocked\|status: partial\|status: human_needed\|status: diagnosed" "$f" && OUTSTANDING="$OUTSTANDING\n$(basename $f)" +done +``` + +**If OUTSTANDING is not empty:** + +Append to the completion confirmation message (regardless of mode): + +``` +Outstanding verification items in this phase: +{list filenames} + +These will carry forward as debt. Review: `/gsd-audit-uat` +``` + +This does NOT block transition — it ensures the user sees the debt before confirming. + **If all plans complete:** @@ -111,7 +151,7 @@ Wait for user decision. Check for lingering handoffs: ```bash -ls .planning/phases/XX-current/.continue-here*.md 2>/dev/null +ls .planning/phases/XX-current/.continue-here*.md 2>/dev/null || true ``` If found, delete them — phase is complete, handoffs are stale. @@ -341,7 +381,7 @@ Resume file: None The `is_last_phase` field from the phase complete result tells you directly: - `is_last_phase: false` → More phases remain → Go to **Route A** -- `is_last_phase: true` → Milestone complete → Go to **Route B** +- `is_last_phase: true` → Last phase done → **Check for workstream collisions first** The `next_phase` and `next_phase_name` fields give you the next phase details. @@ -354,6 +394,34 @@ This returns all phases with goals, disk status, and completion info. --- +**Workstream collision check (when `is_last_phase: true`):** + +Before routing to Route B, check whether other workstreams are still active. +This prevents one workstream from advancing or completing the milestone while +other workstreams are still working on their phases. + +**Skip this check if NOT in workstream mode** (i.e., `GSD_WORKSTREAM` is not set / flat mode). +In flat mode, go directly to **Route B**. + +```bash +# Only check if we're in workstream mode +if [ -n "$GSD_WORKSTREAM" ]; then + WS_LIST=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" workstream list --raw) +fi +``` + +Parse the JSON result. The output has `{ mode, workstreams: [...] }`. +Each workstream entry has: `name`, `status`, `current_phase`, `phase_count`, `completed_phases`. + +Filter out the current workstream (`$GSD_WORKSTREAM`) and any workstreams with +status containing "milestone complete" or "archived" (case-insensitive). +The remaining entries are **other active workstreams**. + +- **If other active workstreams exist** → Go to **Route B1** +- **If NO other active workstreams** (or flat mode) → Go to **Route B** + +--- + **Route A: More phases remain in milestone** read ROADMAP.md to get the next phase's name and goal. @@ -361,7 +429,7 @@ read ROADMAP.md to get the next phase's name and goal. **Check if next phase has CONTEXT.md:** ```bash -ls .planning/phases/*[X+1]*/*-CONTEXT.md 2>/dev/null +ls .planning/phases/*[X+1]*/*-CONTEXT.md 2>/dev/null || true ``` **If next phase exists:** @@ -378,7 +446,7 @@ Next: Phase [X+1] — [Name] ⚡ Auto-continuing: Plan Phase [X+1] in detail ``` -Exit skill and invoke command("/gsd-plan-phase [X+1] --auto") +Exit skill and invoke command("/gsd-plan-phase [X+1] --auto ${GSD_WS}") **If CONTEXT.md does NOT exist:** @@ -390,7 +458,7 @@ Next: Phase [X+1] — [Name] ⚡ Auto-continuing: Discuss Phase [X+1] first ``` -Exit skill and invoke command("/gsd-discuss-phase [X+1] --auto") +Exit skill and invoke command("/gsd-discuss-phase [X+1] --auto ${GSD_WS}") @@ -407,15 +475,15 @@ Exit skill and invoke command("/gsd-discuss-phase [X+1] --auto") **Phase [X+1]: [Name]** — [Goal from ROADMAP.md] -`/gsd-discuss-phase [X+1]` — gather context and clarify approach +`/gsd-discuss-phase [X+1] ${GSD_WS}` — gather context and clarify approach *`/new` first → fresh context window* --- **Also available:** -- `/gsd-plan-phase [X+1]` — skip discussion, plan directly -- `/gsd-research-phase [X+1]` — investigate unknowns +- `/gsd-plan-phase [X+1] ${GSD_WS}` — skip discussion, plan directly +- `/gsd-research-phase [X+1] ${GSD_WS}` — investigate unknowns --- ``` @@ -432,26 +500,85 @@ Exit skill and invoke command("/gsd-discuss-phase [X+1] --auto") **Phase [X+1]: [Name]** — [Goal from ROADMAP.md] *✓ Context gathered, ready to plan* -`/gsd-plan-phase [X+1]` +`/gsd-plan-phase [X+1] ${GSD_WS}` *`/new` first → fresh context window* --- **Also available:** -- `/gsd-discuss-phase [X+1]` — revisit context -- `/gsd-research-phase [X+1]` — investigate unknowns +- `/gsd-discuss-phase [X+1] ${GSD_WS}` — revisit context +- `/gsd-research-phase [X+1] ${GSD_WS}` — investigate unknowns + +--- +``` + + --- + +**Route B1: Workstream done, other workstreams still active** + +This route is reached when `is_last_phase: true` AND the collision check found +other active workstreams. Do NOT suggest completing the milestone or advancing +to the next milestone — other workstreams are still working. + +**Clear auto-advance chain flag** — workstream boundary is the natural stopping point: + +```bash +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-set workflow._auto_chain_active false ``` + + +Override auto-advance: do NOT auto-continue to milestone completion. +Present the blocking information and stop. + +Present (all modes): + +``` +## ✓ Phase {X}: {Phase Name} Complete + +This workstream's phases are complete. Other workstreams are still active: + +| Workstream | Status | Phase | Progress | +|------------|--------|-------|----------| +| {name} | {status} | {current_phase} | {completed_phases}/{phase_count} | +| ... | ... | ... | ... | + +--- + +## Next Steps + +Archive this workstream: + +`/gsd-workstreams complete {current_ws_name} ${GSD_WS}` + +See overall milestone progress: + +`/gsd-workstreams progress ${GSD_WS}` + +*Milestone completion will be available once all workstreams finish.* + +--- +``` + +Do NOT suggest `/gsd-complete-milestone` or `/gsd-new-milestone`. +Do NOT auto-invoke any further slash commands. + +**Stop here.** The user must explicitly decide what to do next. + --- **Route B: Milestone complete (all phases done)** +**This route is only reached when:** +- `is_last_phase: true` AND no other active workstreams exist (or flat mode) + **Clear auto-advance chain flag** — milestone boundary is the natural stopping point: + ```bash node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-set workflow._auto_chain_active false ``` @@ -466,7 +593,7 @@ Phase {X} marked complete. ⚡ Auto-continuing: Complete milestone and archive ``` -Exit skill and invoke command("/gsd-complete-milestone {version}") +Exit skill and invoke command("/gsd-complete-milestone {version} ${GSD_WS}") @@ -483,7 +610,7 @@ Exit skill and invoke command("/gsd-complete-milestone {version}") **Complete Milestone {version}** — archive and prepare for next -`/gsd-complete-milestone {version}` +`/gsd-complete-milestone {version} ${GSD_WS}` *`/new` first → fresh context window* diff --git a/gsd-opencode/get-shit-done/workflows/ui-phase.md b/gsd-opencode/get-shit-done/workflows/ui-phase.md new file mode 100644 index 0000000..c41347f --- /dev/null +++ b/gsd-opencode/get-shit-done/workflows/ui-phase.md @@ -0,0 +1,302 @@ + +Generate a UI design contract (UI-SPEC.md) for frontend phases. Orchestrates gsd-ui-researcher and gsd-ui-checker with a revision loop. Inserts between discuss-phase and plan-phase in the lifecycle. + +UI-SPEC.md locks spacing, typography, color, copywriting, and design system decisions before the planner creates tasks. This prevents design debt caused by ad-hoc styling decisions during execution. + + + +@$HOME/.config/opencode/get-shit-done/references/ui-brand.md + + + +Valid GSD subagent types (use exact names — do not fall back to 'general'): +- gsd-ui-researcher — Researches UI/UX approaches +- gsd-ui-checker — Reviews UI implementation quality + + + + +## 1. Initialize + +```bash +INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init plan-phase "$PHASE") +if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +AGENT_SKILLS_UI=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-ui-researcher 2>/dev/null) +AGENT_SKILLS_UI_CHECKER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-ui-checker 2>/dev/null) +``` + +Parse JSON for: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_context`, `has_research`, `commit_docs`. + +**File paths:** `state_path`, `roadmap_path`, `requirements_path`, `context_path`, `research_path`. + +Resolve UI agent models: + +```bash +UI_RESEARCHER_MODEL=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" resolve-model gsd-ui-researcher --raw) +UI_CHECKER_MODEL=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" resolve-model gsd-ui-checker --raw) +``` + +Check config: + +```bash +UI_ENABLED=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.ui_phase 2>/dev/null || echo "true") +``` + +**If `UI_ENABLED` is `false`:** +``` +UI phase is disabled in config. Enable via /gsd-settings. +``` +Exit workflow. + +**If `planning_exists` is false:** Error — run `/gsd-new-project` first. + +## 2. Parse and Validate Phase + +Extract phase number from $ARGUMENTS. If not provided, detect next unplanned phase. + +```bash +PHASE_INFO=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "${PHASE}") +``` + +**If `found` is false:** Error with available phases. + +## 3. Check Prerequisites + +**If `has_context` is false:** +``` +No CONTEXT.md found for Phase {N}. +Recommended: run /gsd-discuss-phase {N} first to capture design preferences. +Continuing without user decisions — UI researcher will ask all questions. +``` +Continue (non-blocking). + +**If `has_research` is false:** +``` +No RESEARCH.md found for Phase {N}. +Note: stack decisions (component library, styling approach) will be asked during UI research. +``` +Continue (non-blocking). + +## 4. Check Existing UI-SPEC + +```bash +UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1) +``` + +**If exists:** Use question: +- header: "Existing UI-SPEC" +- question: "UI-SPEC.md already exists for Phase {N}. What would you like to do?" +- options: + - "Update — re-run researcher with existing as baseline" + - "View — display current UI-SPEC and exit" + - "Skip — keep current UI-SPEC, proceed to verification" + +If "View": display file contents, exit. +If "Skip": proceed to step 7 (checker). +If "Update": continue to step 5. + +## 5. Spawn gsd-ui-researcher + +Display: +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► UI DESIGN CONTRACT — PHASE {N} +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +◆ Spawning UI researcher... +``` + +Build prompt: + +```markdown +read $HOME/.config/opencode/agents/gsd-ui-researcher.md for instructions. + + +Create UI design contract for Phase {phase_number}: {phase_name} +Answer: "What visual and interaction contracts does this phase need?" + + + +- {state_path} (Project State) +- {roadmap_path} (Roadmap) +- {requirements_path} (Requirements) +- {context_path} (USER DECISIONS from /gsd-discuss-phase) +- {research_path} (Technical Research — stack decisions) + + +${AGENT_SKILLS_UI} + + +write to: {phase_dir}/{padded_phase}-UI-SPEC.md +Template: $HOME/.config/opencode/get-shit-done/templates/UI-SPEC.md + + + +commit_docs: {commit_docs} +phase_dir: {phase_dir} +padded_phase: {padded_phase} + +``` + +Omit null file paths from ``. + +``` +task( + prompt=ui_research_prompt, + subagent_type="gsd-ui-researcher", + model="{UI_RESEARCHER_MODEL}", + description="UI Design Contract Phase {N}" +) +``` + +## 6. Handle Researcher Return + +**If `## UI-SPEC COMPLETE`:** +Display confirmation. Continue to step 7. + +**If `## UI-SPEC BLOCKED`:** +Display blocker details and options. Exit workflow. + +## 7. Spawn gsd-ui-checker + +Display: +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► VERIFYING UI-SPEC +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +◆ Spawning UI checker... +``` + +Build prompt: + +```markdown +read $HOME/.config/opencode/agents/gsd-ui-checker.md for instructions. + + +Validate UI design contract for Phase {phase_number}: {phase_name} +Check all 6 dimensions. Return APPROVED or BLOCKED. + + + +- {phase_dir}/{padded_phase}-UI-SPEC.md (UI Design Contract — PRIMARY INPUT) +- {context_path} (USER DECISIONS — check compliance) +- {research_path} (Technical Research — check stack alignment) + + +${AGENT_SKILLS_UI_CHECKER} + + +ui_safety_gate: {ui_safety_gate config value} + +``` + +``` +task( + prompt=ui_checker_prompt, + subagent_type="gsd-ui-checker", + model="{UI_CHECKER_MODEL}", + description="Verify UI-SPEC Phase {N}" +) +``` + +## 8. Handle Checker Return + +**If `## UI-SPEC VERIFIED`:** +Display dimension results. Proceed to step 10. + +**If `## ISSUES FOUND`:** +Display blocking issues. Proceed to step 9. + +## 9. Revision Loop (Max 2 Iterations) + +Track `revision_count` (starts at 0). + +**If `revision_count` < 2:** +- Increment `revision_count` +- Re-spawn gsd-ui-researcher with revision context: + +```markdown + +The UI checker found issues with the current UI-SPEC.md. + +### Issues to Fix +{paste blocking issues from checker return} + +read the existing UI-SPEC.md, fix ONLY the listed issues, re-write the file. +Do NOT re-ask the user questions that are already answered. + +``` + +- After researcher returns → re-spawn checker (step 7) + +**If `revision_count` >= 2:** +``` +Max revision iterations reached. Remaining issues: + +{list remaining issues} + +Options: +1. Force approve — proceed with current UI-SPEC (FLAGs become accepted) +2. edit manually — open UI-SPEC.md in editor, re-run /gsd-ui-phase +3. Abandon — exit without approving +``` + +Use question for the choice. + +## 10. Present Final Status + +Display: +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► UI-SPEC READY ✓ +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +**Phase {N}: {Name}** — UI design contract approved + +Dimensions: 6/6 passed +{If any FLAGs: "Recommendations: {N} (non-blocking)"} + +─────────────────────────────────────────────────────────────── + +## ▶ Next Up + +**Plan Phase {N}** — planner will use UI-SPEC.md as design context + +`/gsd-plan-phase {N}` + +*/new first → fresh context window* + +─────────────────────────────────────────────────────────────── +``` + +## 11. Commit (if configured) + +```bash +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs(${padded_phase}): UI design contract" --files "${PHASE_DIR}/${PADDED_PHASE}-UI-SPEC.md" +``` + +## 12. Update State + +```bash +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" state record-session \ + --stopped-at "Phase ${PHASE} UI-SPEC approved" \ + --resume-file "${PHASE_DIR}/${PADDED_PHASE}-UI-SPEC.md" +``` + + + + +- [ ] Config checked (exit if ui_phase disabled) +- [ ] Phase validated against roadmap +- [ ] Prerequisites checked (CONTEXT.md, RESEARCH.md — non-blocking warnings) +- [ ] Existing UI-SPEC handled (update/view/skip) +- [ ] gsd-ui-researcher spawned with correct context and file paths +- [ ] UI-SPEC.md created in correct location +- [ ] gsd-ui-checker spawned with UI-SPEC.md +- [ ] All 6 dimensions evaluated +- [ ] Revision loop if BLOCKED (max 2 iterations) +- [ ] Final status displayed with next steps +- [ ] UI-SPEC.md committed (if commit_docs enabled) +- [ ] State updated + diff --git a/gsd-opencode/get-shit-done/workflows/ui-review.md b/gsd-opencode/get-shit-done/workflows/ui-review.md new file mode 100644 index 0000000..a66c7af --- /dev/null +++ b/gsd-opencode/get-shit-done/workflows/ui-review.md @@ -0,0 +1,165 @@ + +Retroactive 6-pillar visual audit of implemented frontend code. Standalone command that works on any project — GSD-managed or not. Produces scored UI-REVIEW.md with actionable findings. + + + +@$HOME/.config/opencode/get-shit-done/references/ui-brand.md + + + +Valid GSD subagent types (use exact names — do not fall back to 'general'): +- gsd-ui-auditor — Audits UI against design requirements + + + + +## 0. Initialize + +```bash +INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE_ARG}") +if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +AGENT_SKILLS_UI_REVIEWER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-ui-reviewer 2>/dev/null) +``` + +Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `commit_docs`. + +```bash +UI_AUDITOR_MODEL=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" resolve-model gsd-ui-auditor --raw) +``` + +Display banner: +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► UI AUDIT — PHASE {N}: {name} +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +## 1. Detect Input State + +```bash +SUMMARY_FILES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null) +UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1) +UI_REVIEW_FILE=$(ls "${PHASE_DIR}"/*-UI-REVIEW.md 2>/dev/null | head -1) +``` + +**If `SUMMARY_FILES` empty:** Exit — "Phase {N} not executed. Run /gsd-execute-phase {N} first." + +**If `UI_REVIEW_FILE` non-empty:** Use question: +- header: "Existing UI Review" +- question: "UI-REVIEW.md already exists for Phase {N}." +- options: + - "Re-audit — run fresh audit" + - "View — display current review and exit" + +If "View": display file, exit. +If "Re-audit": continue. + +## 2. Gather Context Paths + +Build file list for auditor: +- All SUMMARY.md files in phase dir +- All PLAN.md files in phase dir +- UI-SPEC.md (if exists — audit baseline) +- CONTEXT.md (if exists — locked decisions) + +## 3. Spawn gsd-ui-auditor + +``` +◆ Spawning UI auditor... +``` + +Build prompt: + +```markdown +read $HOME/.config/opencode/agents/gsd-ui-auditor.md for instructions. + + +Conduct 6-pillar visual audit of Phase {phase_number}: {phase_name} +{If UI-SPEC exists: "Audit against UI-SPEC.md design contract."} +{If no UI-SPEC: "Audit against abstract 6-pillar standards."} + + + +- {summary_paths} (Execution summaries) +- {plan_paths} (Execution plans — what was intended) +- {ui_spec_path} (UI Design Contract — audit baseline, if exists) +- {context_path} (User decisions, if exists) + + +${AGENT_SKILLS_UI_REVIEWER} + + +phase_dir: {phase_dir} +padded_phase: {padded_phase} + +``` + +Omit null file paths. + +``` +task( + prompt=ui_audit_prompt, + subagent_type="gsd-ui-auditor", + model="{UI_AUDITOR_MODEL}", + description="UI Audit Phase {N}" +) +``` + +## 4. Handle Return + +**If `## UI REVIEW COMPLETE`:** + +Display score summary: + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► UI AUDIT COMPLETE ✓ +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +**Phase {N}: {Name}** — Overall: {score}/24 + +| Pillar | Score | +|--------|-------| +| Copywriting | {N}/4 | +| Visuals | {N}/4 | +| Color | {N}/4 | +| Typography | {N}/4 | +| Spacing | {N}/4 | +| Experience Design | {N}/4 | + +Top fixes: +1. {fix} +2. {fix} +3. {fix} + +Full review: {path to UI-REVIEW.md} + +─────────────────────────────────────────────────────────────── + +## ▶ Next + +- `/gsd-verify-work {N}` — UAT testing +- `/gsd-plan-phase {N+1}` — plan next phase + +*/new first → fresh context window* + +─────────────────────────────────────────────────────────────── +``` + +## 5. Commit (if configured) + +```bash +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs(${padded_phase}): UI audit review" --files "${PHASE_DIR}/${PADDED_PHASE}-UI-REVIEW.md" +``` + + + + +- [ ] Phase validated +- [ ] SUMMARY.md files found (execution completed) +- [ ] Existing review handled (re-audit/view) +- [ ] gsd-ui-auditor spawned with correct context +- [ ] UI-REVIEW.md created in phase directory +- [ ] Score summary displayed to user +- [ ] Next steps presented + diff --git a/gsd-opencode/get-shit-done/workflows/update.md b/gsd-opencode/get-shit-done/workflows/update.md index d019d64..9f3e90d 100644 --- a/gsd-opencode/get-shit-done/workflows/update.md +++ b/gsd-opencode/get-shit-done/workflows/update.md @@ -1,6 +1,6 @@ - + Check for GSD updates via npm, display changelog for versions between installed and latest, obtain user confirmation, and execute clean installation with cache clearing. - + read all files referenced by the invoking prompt's execution_context before starting. @@ -9,23 +9,74 @@ read all files referenced by the invoking prompt's execution_context before star -Detect whether GSD is installed locally or globally by checking both locations and validating install integrity: +Detect whether GSD is installed locally or globally by checking both locations and validating install integrity. + +First, derive `PREFERRED_RUNTIME` from the invoking prompt's `execution_context` path: +- Path contains `/.codex/` -> `codex` +- Path contains `/.gemini/` -> `gemini` +- Path contains `/.config/opencode/` or `/.opencode/` -> `opencode` +- Otherwise -> `OpenCode` + +Use `PREFERRED_RUNTIME` as the first runtime checked so `/gsd-update` targets the runtime that invoked it. ```bash -# Check local first (takes priority only if valid) -# Detect runtime config directory (supports OpenCode, OpenCode, Gemini) -LOCAL_VERSION_FILE="" LOCAL_MARKER_FILE="" LOCAL_DIR="" -for dir in .OpenCode .config/opencode .opencode .gemini; do - if [ -f "./$dir/get-shit-done/VERSION" ]; then +# Runtime candidates: ":" stored as an array. +# Using an array instead of a space-separated string ensures correct +# iteration in both bash and zsh (zsh does not word-split unquoted +# variables by default). Fixes #1173. +RUNTIME_DIRS=( "OpenCode:.OpenCode" "opencode:.config/opencode" "opencode:.opencode" "gemini:.gemini" "codex:.codex" ) + +# PREFERRED_RUNTIME should be set from execution_context before running this block. +# If not set, infer from runtime env vars; fallback to OpenCode. +if [ -z "$PREFERRED_RUNTIME" ]; then + if [ -n "$CODEX_HOME" ]; then + PREFERRED_RUNTIME="codex" + elif [ -n "$GEMINI_CONFIG_DIR" ]; then + PREFERRED_RUNTIME="gemini" + elif [ -n "$OPENCODE_CONFIG_DIR" ] || [ -n "$OPENCODE_CONFIG" ]; then + PREFERRED_RUNTIME="opencode" + elif [ -n "$CLAUDE_CONFIG_DIR" ]; then + PREFERRED_RUNTIME="OpenCode" + else + PREFERRED_RUNTIME="OpenCode" + fi +fi + +# Reorder entries so preferred runtime is checked first. +ORDERED_RUNTIME_DIRS=() +for entry in "${RUNTIME_DIRS[@]}"; do + runtime="${entry%%:*}" + if [ "$runtime" = "$PREFERRED_RUNTIME" ]; then + ORDERED_RUNTIME_DIRS+=( "$entry" ) + fi +done +for entry in "${RUNTIME_DIRS[@]}"; do + runtime="${entry%%:*}" + if [ "$runtime" != "$PREFERRED_RUNTIME" ]; then + ORDERED_RUNTIME_DIRS+=( "$entry" ) + fi +done + +# Check local first (takes priority only if valid and distinct from global) +LOCAL_VERSION_FILE="" LOCAL_MARKER_FILE="" LOCAL_DIR="" LOCAL_RUNTIME="" +for entry in "${ORDERED_RUNTIME_DIRS[@]}"; do + runtime="${entry%%:*}" + dir="${entry#*:}" + if [ -f "./$dir/get-shit-done/VERSION" ] || [ -f "./$dir/get-shit-done/workflows/update.md" ]; then + LOCAL_RUNTIME="$runtime" LOCAL_VERSION_FILE="./$dir/get-shit-done/VERSION" LOCAL_MARKER_FILE="./$dir/get-shit-done/workflows/update.md" LOCAL_DIR="$(cd "./$dir" 2>/dev/null && pwd)" break fi done -GLOBAL_VERSION_FILE="" GLOBAL_MARKER_FILE="" GLOBAL_DIR="" -for dir in .OpenCode .config/opencode .opencode .gemini; do - if [ -f "$HOME/$dir/get-shit-done/VERSION" ]; then + +GLOBAL_VERSION_FILE="" GLOBAL_MARKER_FILE="" GLOBAL_DIR="" GLOBAL_RUNTIME="" +for entry in "${ORDERED_RUNTIME_DIRS[@]}"; do + runtime="${entry%%:*}" + dir="${entry#*:}" + if [ -f "$HOME/$dir/get-shit-done/VERSION" ] || [ -f "$HOME/$dir/get-shit-done/workflows/update.md" ]; then + GLOBAL_RUNTIME="$runtime" GLOBAL_VERSION_FILE="$HOME/$dir/get-shit-done/VERSION" GLOBAL_MARKER_FILE="$HOME/$dir/get-shit-done/workflows/update.md" GLOBAL_DIR="$(cd "$HOME/$dir" 2>/dev/null && pwd)" @@ -42,20 +93,40 @@ if [ -n "$LOCAL_VERSION_FILE" ] && [ -f "$LOCAL_VERSION_FILE" ] && [ -f "$LOCAL_ fi if [ "$IS_LOCAL" = true ]; then - cat "$LOCAL_VERSION_FILE" - echo "LOCAL" + INSTALLED_VERSION="$(cat "$LOCAL_VERSION_FILE")" + INSTALL_SCOPE="LOCAL" + TARGET_RUNTIME="$LOCAL_RUNTIME" elif [ -n "$GLOBAL_VERSION_FILE" ] && [ -f "$GLOBAL_VERSION_FILE" ] && [ -f "$GLOBAL_MARKER_FILE" ] && grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+' "$GLOBAL_VERSION_FILE"; then - cat "$GLOBAL_VERSION_FILE" - echo "GLOBAL" + INSTALLED_VERSION="$(cat "$GLOBAL_VERSION_FILE")" + INSTALL_SCOPE="GLOBAL" + TARGET_RUNTIME="$GLOBAL_RUNTIME" +elif [ -n "$LOCAL_RUNTIME" ] && [ -f "$LOCAL_MARKER_FILE" ]; then + # Runtime detected but VERSION missing/corrupt: treat as unknown version, keep runtime target + INSTALLED_VERSION="0.0.0" + INSTALL_SCOPE="LOCAL" + TARGET_RUNTIME="$LOCAL_RUNTIME" +elif [ -n "$GLOBAL_RUNTIME" ] && [ -f "$GLOBAL_MARKER_FILE" ]; then + INSTALLED_VERSION="0.0.0" + INSTALL_SCOPE="GLOBAL" + TARGET_RUNTIME="$GLOBAL_RUNTIME" else - echo "UNKNOWN" + INSTALLED_VERSION="0.0.0" + INSTALL_SCOPE="UNKNOWN" + TARGET_RUNTIME="OpenCode" fi + +echo "$INSTALLED_VERSION" +echo "$INSTALL_SCOPE" +echo "$TARGET_RUNTIME" ``` Parse output: -- If last line is "LOCAL": local install is valid; installed version is first line; use `--local` -- If last line is "GLOBAL": local missing/invalid, global install is valid; installed version is first line; use `--global` -- If "UNKNOWN": proceed to install step (treat as version 0.0.0) +- Line 1 = installed version (`0.0.0` means unknown version) +- Line 2 = install scope (`LOCAL`, `GLOBAL`, or `UNKNOWN`) +- Line 3 = target runtime (`OpenCode`, `opencode`, `gemini`, or `codex`) +- If scope is `UNKNOWN`, proceed to install step using `--OpenCode --global` fallback. + +If multiple runtime installs are detected and the invoking runtime cannot be determined from execution_context, ask the user which runtime to update before running install. **If VERSION file missing:** ``` @@ -149,7 +220,9 @@ Exit. - `get-shit-done/` will be wiped and replaced - `agents/gsd-*` files will be replaced -(Paths are relative to your install location: `$HOME/.config/opencode/` for global, `./.OpenCode/` for local) +(Paths are relative to detected runtime install location: +global: `$HOME/.config/opencode/`, `~/.config/opencode/`, `~/.opencode/`, `~/.gemini/`, or `~/.codex/` +local: `./.OpenCode/`, `./.config/opencode/`, `./.opencode/`, `./.gemini/`, or `./.codex/`) Your custom files in other locations are preserved: - Custom commands not in `commands/gsd/` ✓ @@ -172,14 +245,24 @@ Use question: Run the update using the install type detected in step 1: +Build runtime flag from step 1: +```bash +RUNTIME_FLAG="--$TARGET_RUNTIME" +``` + **If LOCAL install:** ```bash -npx -y gsd-opencode@latest --local +npx -y gsd-opencode@latest "$RUNTIME_FLAG" --local +``` + +**If GLOBAL install:** +```bash +npx -y gsd-opencode@latest "$RUNTIME_FLAG" --global ``` -**If GLOBAL install (or unknown):** +**If UNKNOWN install:** ```bash -npx -y gsd-opencode@latest --global +npx -y gsd-opencode@latest --OpenCode --global ``` Capture output. If install fails, show error and exit. @@ -188,7 +271,7 @@ Clear the update cache so statusline indicator disappears: ```bash # Clear update cache across all runtime directories -for dir in .OpenCode .config/opencode .opencode .gemini; do +for dir in .OpenCode .config/opencode .opencode .gemini .codex; do rm -f "./$dir/cache/gsd-update-check.json" rm -f "$HOME/$dir/cache/gsd-update-check.json" done @@ -205,7 +288,7 @@ Format completion message (changelog was already shown in confirmation step): ║ GSD Updated: v1.5.10 → v1.5.15 ║ ╚═══════════════════════════════════════════════════════════╝ -⚠️ Restart OpenCode to pick up the new commands. +⚠️ Restart your runtime to pick up the new commands. [View full changelog](https://github.com/rokicool/gsd-opencode/blob/main/CHANGELOG.md) ``` diff --git a/gsd-opencode/get-shit-done/workflows/validate-phase.md b/gsd-opencode/get-shit-done/workflows/validate-phase.md index d3f802e..b708bc3 100644 --- a/gsd-opencode/get-shit-done/workflows/validate-phase.md +++ b/gsd-opencode/get-shit-done/workflows/validate-phase.md @@ -1,11 +1,16 @@ - + Audit Nyquist validation gaps for a completed phase. Generate missing tests. Update VALIDATION.md. - + @$HOME/.config/opencode/get-shit-done/references/ui-brand.md + +Valid GSD subagent types (use exact names — do not fall back to 'general'): +- gsd-nyquist-auditor — Validates verification coverage + + ## 0. Initialize @@ -13,13 +18,14 @@ Audit Nyquist validation gaps for a completed phase. Generate missing tests. Upd ```bash INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init phase-op "${PHASE_ARG}") if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +AGENT_SKILLS_AUDITOR=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-nyquist-auditor 2>/dev/null) ``` Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`. ```bash AUDITOR_MODEL=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" resolve-model gsd-nyquist-auditor --raw) -NYQUIST_CFG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config get workflow.nyquist_validation --raw) +NYQUIST_CFG=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.nyquist_validation --raw) ``` If `NYQUIST_CFG` is `false`: exit with "Nyquist validation is disabled. Enable via /gsd-settings." @@ -35,7 +41,7 @@ SUMMARY_FILES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null) - **State A** (`VALIDATION_FILE` non-empty): Audit existing - **State B** (`VALIDATION_FILE` empty, `SUMMARY_FILES` non-empty): Reconstruct from artifacts -- **State C** (`SUMMARY_FILES` empty): Exit — "Phase {N} not executed. Run /gsd-execute-phase {N} first." +- **State C** (`SUMMARY_FILES` empty): Exit — "Phase {N} not executed. Run /gsd-execute-phase {N} ${GSD_WS} first." ## 2. Discovery @@ -90,7 +96,8 @@ task( "{PLAN, SUMMARY, impl files, VALIDATION.md}" + "{gap list}" + "{framework, config, commands}" + - "Never modify impl files. Max 3 debug iterations. Escalate impl bugs.", + "Never modify impl files. Max 3 debug iterations. Escalate impl bugs." + + "${AGENT_SKILLS_AUDITOR}", subagent_type="gsd-nyquist-auditor", model="{AUDITOR_MODEL}", description="Fill validation gaps for Phase {N}" @@ -128,7 +135,7 @@ Handle return: git add {test_files} git commit -m "test(phase-${PHASE}): add Nyquist validation tests" -node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit-docs "docs(phase-${PHASE}): add/update validation strategy" +node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs(phase-${PHASE}): add/update validation strategy" ``` ## 8. Results + Routing @@ -137,14 +144,14 @@ node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" commit-docs "docs( ``` GSD > PHASE {N} IS NYQUIST-COMPLIANT All requirements have automated verification. -▶ Next: /gsd-audit-milestone +▶ Next: /gsd-audit-milestone ${GSD_WS} ``` **Partial:** ``` GSD > PHASE {N} VALIDATED (PARTIAL) {M} automated, {K} manual-only. -▶ Retry: /gsd-validate-phase {N} +▶ Retry: /gsd-validate-phase {N} ${GSD_WS} ``` Display `/new` reminder. diff --git a/gsd-opencode/get-shit-done/workflows/verify-phase.md b/gsd-opencode/get-shit-done/workflows/verify-phase.md index a3afbab..4373180 100644 --- a/gsd-opencode/get-shit-done/workflows/verify-phase.md +++ b/gsd-opencode/get-shit-done/workflows/verify-phase.md @@ -1,8 +1,8 @@ - + Verify phase goal achievement through goal-backward analysis. Check that the codebase delivers what the phase promised, not just that tasks completed. Executed by a verification subagent spawned from execute-phase.md. - + **task completion ≠ Goal achievement** @@ -37,8 +37,8 @@ Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `has_plans`, Then load phase details and list plans/summaries: ```bash node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "${phase_number}" -grep -E "^| ${phase_number}" .planning/REQUIREMENTS.md 2>/dev/null -ls "$phase_dir"/*-SUMMARY.md "$phase_dir"/*-PLAN.md 2>/dev/null +grep -E "^| ${phase_number}" .planning/REQUIREMENTS.md 2>/dev/null || true +ls "$phase_dir"/*-SUMMARY.md "$phase_dir"/*-PLAN.md 2>/dev/null || true ``` Extract **phase goal** from ROADMAP.md (the outcome to verify, not tasks) and **requirements** from REQUIREMENTS.md if it exists. @@ -126,6 +126,17 @@ WIRED = imported AND used. ORPHANED = exists but not imported/used. | ✓ | ✓ | ✗ | ⚠️ ORPHANED | | ✓ | ✗ | - | ✗ STUB | | ✗ | - | - | ✗ MISSING | + +**Export-level spot check (WARNING severity):** + +For artifacts that pass Level 3, spot-check individual exports: +- Extract key exported symbols (functions, constants, classes — skip types/interfaces) +- For each, grep for usage outside the defining file +- Flag exports with zero external call sites as "exported but unused" + +This catches dead stores like `setPlan()` that exist in a wired file but are +never actually called. Report as WARNING — may indicate incomplete cross-plan +wiring or leftover code from plan revisions. @@ -160,7 +171,7 @@ Record status and evidence for each key link. If REQUIREMENTS.md exists: ```bash -grep -E "Phase ${PHASE_NUM}" .planning/REQUIREMENTS.md 2>/dev/null +grep -E "Phase ${PHASE_NUM}" .planning/REQUIREMENTS.md 2>/dev/null || true ``` For each requirement: parse description → identify supporting truths/artifacts → status: ✓ SATISFIED / ✗ BLOCKED / ? NEEDS HUMAN. diff --git a/gsd-opencode/get-shit-done/workflows/verify-work.md b/gsd-opencode/get-shit-done/workflows/verify-work.md index 5268cd2..e167fe7 100644 --- a/gsd-opencode/get-shit-done/workflows/verify-work.md +++ b/gsd-opencode/get-shit-done/workflows/verify-work.md @@ -1,8 +1,14 @@ - + Validate built features through conversational testing with persistent state. Creates UAT.md that tracks test progress, survives /new, and feeds gaps into /gsd-plan-phase --gaps. User tests, OpenCode records. One test at a time. Plain text responses. - + + + +Valid GSD subagent types (use exact names — do not fall back to 'general'): +- gsd-planner — Creates detailed plans from phase scope +- gsd-plan-checker — Reviews plan quality before execution + **Show expected, ask if reality matches.** @@ -26,16 +32,18 @@ If $ARGUMENTS contains a phase number, load context: ```bash INIT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" init verify-work "${PHASE_ARG}") if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +AGENT_SKILLS_PLANNER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-planner 2>/dev/null) +AGENT_SKILLS_CHECKER=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-checker 2>/dev/null) ``` -Parse JSON for: `planner_model`, `checker_model`, `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `has_verification`. +Parse JSON for: `planner_model`, `checker_model`, `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `has_verification`, `uat_path`. **First: Check for active UAT sessions** ```bash -find .planning/phases -name "*-UAT.md" -type f 2>/dev/null | head -5 +(find .planning/phases -name "*-UAT.md" -type f 2>/dev/null || true) | head -5 ``` **If active sessions exist AND no $ARGUMENTS provided:** @@ -84,7 +92,7 @@ Continue to `create_uat_file`. Use `phase_dir` from init (or run init if not already done). ```bash -ls "$phase_dir"/*-SUMMARY.md 2>/dev/null +ls "$phase_dir"/*-SUMMARY.md 2>/dev/null || true ``` read each SUMMARY.md to extract testable deliverables. @@ -186,23 +194,23 @@ Proceed to `present_test`. **Present current test to user:** -read Current Test section from UAT file. - -Display using checkpoint box format: +Render the checkpoint from the structured UAT file instead of composing it freehand: +```bash +CHECKPOINT=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" uat render-checkpoint --file "$uat_path" --raw) +if [[ "$CHECKPOINT" == @file:* ]]; then CHECKPOINT=$(cat "${CHECKPOINT#@file:}"); fi ``` -╔══════════════════════════════════════════════════════════════╗ -║ CHECKPOINT: Verification Required ║ -╚══════════════════════════════════════════════════════════════╝ -**Test {number}: {name}** +Display the returned checkpoint EXACTLY as-is: -{expected} - -────────────────────────────────────────────────────────────── -→ Type "pass" or describe what's wrong -────────────────────────────────────────────────────────────── ``` +{CHECKPOINT} +``` + +**Critical response hygiene:** +- Your entire response MUST equal `{CHECKPOINT}` byte-for-byte. +- Do NOT add commentary before or after the block. +- If you notice protocol/meta markers such as `to=all:`, role-routing text, XML system tags, hidden instruction markers, ad copy, or any unrelated suffix, discard the draft and output `{CHECKPOINT}` only. Wait for user response (plain text, no question). @@ -231,6 +239,29 @@ result: skipped reason: [user's reason if provided] ``` +**If response indicates blocked:** +- "blocked", "can't test - server not running", "need physical device", "need release build" +- Or any response containing: "server", "blocked", "not running", "physical device", "release build" + +Infer blocked_by tag from response: +- Contains: server, not running, gateway, API → `server` +- Contains: physical, device, hardware, real phone → `physical-device` +- Contains: release, preview, build, EAS → `release-build` +- Contains: stripe, twilio, third-party, configure → `third-party` +- Contains: depends on, prior phase, prerequisite → `prior-phase` +- Default: `other` + +Update Tests section: +``` +### {N}. {name} +expected: {expected} +result: blocked +blocked_by: {inferred tag} +reason: "{verbatim user response}" +``` + +Note: Blocked tests do NOT go into the Gaps section (they aren't code issues — they're prerequisite gates). + **If response is anything else:** - Treat as issue description @@ -293,8 +324,24 @@ Proceed to `present_test`. **Complete testing and commit:** +**Determine final status:** + +Count results: +- `pending_count`: tests with `result: [pending]` +- `blocked_count`: tests with `result: blocked` +- `skipped_no_reason`: tests with `result: skipped` and no `reason` field + +``` +if pending_count > 0 OR blocked_count > 0 OR skipped_no_reason > 0: + status: partial + # Session ended but not all tests resolved +else: + status: complete + # All tests have a definitive result (pass, issue, or skipped-with-reason) +``` + Update frontmatter: -- status: complete +- status: {computed status} - updated: [now] Clear Current Test section: @@ -333,6 +380,7 @@ All tests passed. Ready to continue. - `/gsd-plan-phase {next}` — Plan next phase - `/gsd-execute-phase {next}` — Execute next phase +- `/gsd-ui-review {phase}` — visual quality audit (if frontend files were modified) ``` @@ -385,6 +433,8 @@ task( - .planning/ROADMAP.md (Roadmap) +${AGENT_SKILLS_PLANNER} + @@ -431,6 +481,8 @@ task( - {phase_dir}/*-PLAN.md (Plans to verify) +${AGENT_SKILLS_CHECKER} + @@ -471,6 +523,8 @@ task( - {phase_dir}/*-PLAN.md (Existing plans) +${AGENT_SKILLS_PLANNER} + **Checker issues:** {structured_issues_from_checker} diff --git a/gsd-opencode/skills/gsd-audit-milestone/SKILL.md b/gsd-opencode/skills/gsd-audit-milestone/SKILL.md new file mode 100644 index 0000000..497e20d --- /dev/null +++ b/gsd-opencode/skills/gsd-audit-milestone/SKILL.md @@ -0,0 +1,29 @@ +--- +name: gsd-audit-milestone +description: Implementation of gsd-audit-milestone command +--- + + +Verify milestone achieved its definition of done. Check requirements coverage, cross-phase integration, and end-to-end flows. + +**This command IS the orchestrator.** Reads existing VERIFICATION.md files (phases already verified during execute-phase), aggregates tech debt and deferred gaps, then spawns integration checker for cross-phase wiring. + + + +@$HOME/.config/opencode/get-shit-done/workflows/audit-milestone.md + + + +Version: $ARGUMENTS (optional — defaults to current milestone) + +Core planning files are resolved in-workflow (`init milestone-op`) and loaded only as needed. + +**Completed Work:** +glob: .planning/phases/*/*-SUMMARY.md +glob: .planning/phases/*/*-VERIFICATION.md + + + +Execute the audit-milestone workflow from @$HOME/.config/opencode/get-shit-done/workflows/audit-milestone.md end-to-end. +Preserve all workflow gates (scope determination, verification reading, integration check, requirements coverage, routing). + diff --git a/gsd-opencode/skills/gsd-cleanup/SKILL.md b/gsd-opencode/skills/gsd-cleanup/SKILL.md new file mode 100644 index 0000000..452bed6 --- /dev/null +++ b/gsd-opencode/skills/gsd-cleanup/SKILL.md @@ -0,0 +1,19 @@ +--- +name: gsd-cleanup +description: Implementation of gsd-cleanup command +--- + + +Archive phase directories from completed milestones into `.planning/milestones/v{X.Y}-phases/`. + +Use when `.planning/phases/` has accumulated directories from past milestones. + + + +@$HOME/.config/opencode/get-shit-done/workflows/cleanup.md + + + +Follow the cleanup workflow at @$HOME/.config/opencode/get-shit-done/workflows/cleanup.md. +Identify completed milestones, show a dry-run summary, and archive on confirmation. + diff --git a/gsd-opencode/skills/gsd-complete-milestone/SKILL.md b/gsd-opencode/skills/gsd-complete-milestone/SKILL.md new file mode 100644 index 0000000..2540f8b --- /dev/null +++ b/gsd-opencode/skills/gsd-complete-milestone/SKILL.md @@ -0,0 +1,131 @@ +--- +name: gsd-complete-milestone +description: Implementation of gsd-complete-milestone command +--- + + + +Mark milestone {{version}} complete, archive to milestones/, and update ROADMAP.md and REQUIREMENTS.md. + +Purpose: Create historical record of shipped version, archive milestone artifacts (roadmap + requirements), and prepare for next milestone. +Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tagged. + + + +**Load these files NOW (before proceeding):** + +- @$HOME/.config/opencode/get-shit-done/workflows/complete-milestone.md (main workflow) +- @$HOME/.config/opencode/get-shit-done/templates/milestone-archive.md (archive template) + + + +**Project files:** +- `.planning/ROADMAP.md` +- `.planning/REQUIREMENTS.md` +- `.planning/STATE.md` +- `.planning/PROJECT.md` + +**User input:** + +- Version: {{version}} (e.g., "1.0", "1.1", "2.0") + + + + +**Follow complete-milestone.md workflow:** + +0. **Check for audit:** + + - Look for `.planning/v{{version}}-MILESTONE-AUDIT.md` + - If missing or stale: recommend `/gsd-audit-milestone` first + - If audit status is `gaps_found`: recommend `/gsd-plan-milestone-gaps` first + - If audit status is `passed`: proceed to step 1 + + ```markdown + ## Pre-flight Check + + {If no v{{version}}-MILESTONE-AUDIT.md:} + ⚠ No milestone audit found. Run `/gsd-audit-milestone` first to verify + requirements coverage, cross-phase integration, and E2E flows. + + {If audit has gaps:} + ⚠ Milestone audit found gaps. Run `/gsd-plan-milestone-gaps` to create + phases that close the gaps, or proceed anyway to accept as tech debt. + + {If audit passed:} + ✓ Milestone audit passed. Proceeding with completion. + ``` + +1. **Verify readiness:** + + - Check all phases in milestone have completed plans (SUMMARY.md exists) + - Present milestone scope and stats + - Wait for confirmation + +2. **Gather stats:** + + - Count phases, plans, tasks + - Calculate git range, file changes, LOC + - Extract timeline from git log + - Present summary, confirm + +3. **Extract accomplishments:** + + - read all phase SUMMARY.md files in milestone range + - Extract 4-6 key accomplishments + - Present for approval + +4. **Archive milestone:** + + - Create `.planning/milestones/v{{version}}-ROADMAP.md` + - Extract full phase details from ROADMAP.md + - Fill milestone-archive.md template + - Update ROADMAP.md to one-line summary with link + +5. **Archive requirements:** + + - Create `.planning/milestones/v{{version}}-REQUIREMENTS.md` + - Mark all v1 requirements as complete (checkboxes checked) + - Note requirement outcomes (validated, adjusted, dropped) + - Delete `.planning/REQUIREMENTS.md` (fresh one created for next milestone) + +6. **Update PROJECT.md:** + + - Add "Current State" section with shipped version + - Add "Next Milestone Goals" section + - Archive previous content in `
` (if v1.1+) + +7. **Commit and tag:** + + - Stage: MILESTONES.md, PROJECT.md, ROADMAP.md, STATE.md, archive files + - Commit: `chore: archive v{{version}} milestone` + - Tag: `git tag -a v{{version}} -m "[milestone summary]"` + - Ask about pushing tag + +8. **Offer next steps:** + - `/gsd-new-milestone` — start next milestone (questioning → research → requirements → roadmap) + + + + + +- Milestone archived to `.planning/milestones/v{{version}}-ROADMAP.md` +- Requirements archived to `.planning/milestones/v{{version}}-REQUIREMENTS.md` +- `.planning/REQUIREMENTS.md` deleted (fresh for next milestone) +- ROADMAP.md collapsed to one-line entry +- PROJECT.md updated with current state +- Git tag v{{version}} created +- Commit successful +- User knows next steps (including need for fresh requirements) + + + + +- **Load workflow first:** read complete-milestone.md before executing +- **Verify completion:** All phases must have SUMMARY.md files +- **User confirmation:** Wait for approval at verification gates +- **Archive before deleting:** Always create archive files before updating/deleting originals +- **One-line summary:** Collapsed milestone in ROADMAP.md should be single line with link +- **Context efficiency:** Archive keeps ROADMAP.md and REQUIREMENTS.md constant size per milestone +- **Fresh requirements:** Next milestone starts with `/gsd-new-milestone` which includes requirements definition + diff --git a/gsd-opencode/skills/gsd-discuss-phase/SKILL.md b/gsd-opencode/skills/gsd-discuss-phase/SKILL.md new file mode 100644 index 0000000..4aedfc4 --- /dev/null +++ b/gsd-opencode/skills/gsd-discuss-phase/SKILL.md @@ -0,0 +1,54 @@ +--- +name: gsd-discuss-phase +description: Implementation of gsd-discuss-phase command +--- + + + +Extract implementation decisions that downstream agents need — researcher and planner will use CONTEXT.md to know what to investigate and what choices are locked. + +**How it works:** +1. Load prior context (PROJECT.md, REQUIREMENTS.md, STATE.md, prior CONTEXT.md files) +2. Scout codebase for reusable assets and patterns +3. Analyze phase — skip gray areas already decided in prior phases +4. Present remaining gray areas — user selects which to discuss +5. Deep-dive each selected area until satisfied +6. Create CONTEXT.md with decisions that guide research and planning + +**Output:** `{phase_num}-CONTEXT.md` — decisions clear enough that downstream agents can act without asking the user again + + + +@$HOME/.config/opencode/get-shit-done/workflows/discuss-phase.md +@$HOME/.config/opencode/get-shit-done/workflows/discuss-phase-assumptions.md +@$HOME/.config/opencode/get-shit-done/templates/context.md + + + +Phase number: $ARGUMENTS (required) + +Context files are resolved in-workflow using `init phase-op` and roadmap/state tool calls. + + + +**Mode routing:** +```bash +DISCUSS_MODE=$(node "$HOME/.config/opencode/get-shit-done/bin/gsd-tools.cjs" config-get workflow.discuss_mode 2>/dev/null || echo "discuss") +``` + +If `DISCUSS_MODE` is `"assumptions"`: read and execute @$HOME/.config/opencode/get-shit-done/workflows/discuss-phase-assumptions.md end-to-end. + +If `DISCUSS_MODE` is `"discuss"` (or unset, or any other value): read and execute @$HOME/.config/opencode/get-shit-done/workflows/discuss-phase.md end-to-end. + +**MANDATORY:** The execution_context files listed above ARE the instructions. read the workflow file BEFORE taking any action. The objective and success_criteria sections in this command file are summaries — the workflow file contains the complete step-by-step process with all required behaviors, config checks, and interaction patterns. Do not improvise from the summary. + + + +- Prior context loaded and applied (no re-asking decided questions) +- Gray areas identified through intelligent analysis +- User chose which areas to discuss +- Each selected area explored until satisfied +- Scope creep redirected to deferred ideas +- CONTEXT.md captures decisions, not vague vision +- User knows next steps + diff --git a/gsd-opencode/skills/gsd-execute-phase/SKILL.md b/gsd-opencode/skills/gsd-execute-phase/SKILL.md new file mode 100644 index 0000000..fcf8d4d --- /dev/null +++ b/gsd-opencode/skills/gsd-execute-phase/SKILL.md @@ -0,0 +1,49 @@ +--- +name: gsd-execute-phase +description: Implementation of gsd-execute-phase command +--- + + +Execute all plans in a phase using wave-based parallel execution. + +Orchestrator stays lean: discover plans, analyze dependencies, group into waves, spawn subagents, collect results. Each subagent loads the full execute-plan context and handles its own plan. + +Optional wave filter: +- `--wave N` executes only Wave `N` for pacing, quota management, or staged rollout +- phase verification/completion still only happens when no incomplete plans remain after the selected wave finishes + +Flag handling rule: +- The optional flags documented below are available behaviors, not implied active behaviors +- A flag is active only when its literal token appears in `$ARGUMENTS` +- If a documented flag is absent from `$ARGUMENTS`, treat it as inactive + +Context budget: ~15% orchestrator, 100% fresh per subagent. + + + +@$HOME/.config/opencode/get-shit-done/workflows/execute-phase.md +@$HOME/.config/opencode/get-shit-done/references/ui-brand.md + + + +Phase: $ARGUMENTS + +**Available optional flags (documentation only — not automatically active):** +- `--wave N` — Execute only Wave `N` in the phase. Use when you want to pace execution or stay inside usage limits. +- `--gaps-only` — Execute only gap closure plans (plans with `gap_closure: true` in frontmatter). Use after verify-work creates fix plans. +- `--interactive` — Execute plans sequentially inline (no subagents) with user checkpoints between tasks. Lower token usage, pair-programming style. Best for small phases, bug fixes, and verification gaps. + +**Active flags must be derived from `$ARGUMENTS`:** +- `--wave N` is active only if the literal `--wave` token is present in `$ARGUMENTS` +- `--gaps-only` is active only if the literal `--gaps-only` token is present in `$ARGUMENTS` +- `--interactive` is active only if the literal `--interactive` token is present in `$ARGUMENTS` +- If none of these tokens appear, run the standard full-phase execution flow with no flag-specific filtering +- Do not infer that a flag is active just because it is documented in this prompt + +Context files are resolved inside the workflow via `gsd-tools init execute-phase` and per-subagent `` blocks. + + + +Execute the execute-phase workflow from @$HOME/.config/opencode/get-shit-done/workflows/execute-phase.md end-to-end. +Preserve all workflow gates (wave execution, checkpoint handling, verification, state updates, routing). + diff --git a/gsd-opencode/skills/gsd-plan-phase/SKILL.md b/gsd-opencode/skills/gsd-plan-phase/SKILL.md new file mode 100644 index 0000000..f4cce7f --- /dev/null +++ b/gsd-opencode/skills/gsd-plan-phase/SKILL.md @@ -0,0 +1,37 @@ +--- +name: gsd-plan-phase +description: Implementation of gsd-plan-phase command +--- + + +Create executable phase prompts (PLAN.md files) for a roadmap phase with integrated research and verification. + +**Default flow:** Research (if needed) → Plan → Verify → Done + +**Orchestrator role:** Parse arguments, validate phase, research domain (unless skipped), spawn gsd-planner, verify with gsd-plan-checker, iterate until pass or max iterations, present results. + + + +@$HOME/.config/opencode/get-shit-done/workflows/plan-phase.md +@$HOME/.config/opencode/get-shit-done/references/ui-brand.md + + + +Phase number: $ARGUMENTS (optional — auto-detects next unplanned phase if omitted) + +**Flags:** +- `--research` — Force re-research even if RESEARCH.md exists +- `--skip-research` — Skip research, go straight to planning +- `--gaps` — Gap closure mode (reads VERIFICATION.md, skips research) +- `--skip-verify` — Skip verification loop +- `--prd ` — Use a PRD/acceptance criteria file instead of discuss-phase. Parses requirements into CONTEXT.md automatically. Skips discuss-phase entirely. +- `--reviews` — Replan incorporating cross-AI review feedback from REVIEWS.md (produced by `/gsd-review`) +- `--text` — Use plain-text numbered lists instead of TUI menus (required for `/rc` remote sessions) + +Normalize phase input in step 2 before any directory lookups. + + + +Execute the plan-phase workflow from @$HOME/.config/opencode/get-shit-done/workflows/plan-phase.md end-to-end. +Preserve all workflow gates (validation, research, planning, verification loop, routing). + diff --git a/gsd-opencode/skills/gsd-ui-phase/SKILL.md b/gsd-opencode/skills/gsd-ui-phase/SKILL.md new file mode 100644 index 0000000..30bc235 --- /dev/null +++ b/gsd-opencode/skills/gsd-ui-phase/SKILL.md @@ -0,0 +1,24 @@ +--- +name: gsd-ui-phase +description: Implementation of gsd-ui-phase command +--- + + +Create a UI design contract (UI-SPEC.md) for a frontend phase. +Orchestrates gsd-ui-researcher and gsd-ui-checker. +Flow: Validate → Research UI → Verify UI-SPEC → Done + + + +@$HOME/.config/opencode/get-shit-done/workflows/ui-phase.md +@$HOME/.config/opencode/get-shit-done/references/ui-brand.md + + + +Phase number: $ARGUMENTS — optional, auto-detects next unplanned phase if omitted. + + + +Execute @$HOME/.config/opencode/get-shit-done/workflows/ui-phase.md end-to-end. +Preserve all workflow gates. + diff --git a/gsd-opencode/skills/gsd-ui-review/SKILL.md b/gsd-opencode/skills/gsd-ui-review/SKILL.md new file mode 100644 index 0000000..3f5f888 --- /dev/null +++ b/gsd-opencode/skills/gsd-ui-review/SKILL.md @@ -0,0 +1,24 @@ +--- +name: gsd-ui-review +description: Implementation of gsd-ui-review command +--- + + +Conduct a retroactive 6-pillar visual audit. Produces UI-REVIEW.md with +graded assessment (1-4 per pillar). Works on any project. +Output: {phase_num}-UI-REVIEW.md + + + +@$HOME/.config/opencode/get-shit-done/workflows/ui-review.md +@$HOME/.config/opencode/get-shit-done/references/ui-brand.md + + + +Phase: $ARGUMENTS — optional, defaults to last completed phase. + + + +Execute @$HOME/.config/opencode/get-shit-done/workflows/ui-review.md end-to-end. +Preserve all workflow gates. + diff --git a/gsd-opencode/skills/gsd-verify-work/SKILL.md b/gsd-opencode/skills/gsd-verify-work/SKILL.md new file mode 100644 index 0000000..d1ef603 --- /dev/null +++ b/gsd-opencode/skills/gsd-verify-work/SKILL.md @@ -0,0 +1,30 @@ +--- +name: gsd-verify-work +description: Implementation of gsd-verify-work command +--- + + +Validate built features through conversational testing with persistent state. + +Purpose: Confirm what OpenCode built actually works from user's perspective. One test at a time, plain text responses, no interrogation. When issues are found, automatically diagnose, plan fixes, and prepare for execution. + +Output: {phase_num}-UAT.md tracking all test results. If issues found: diagnosed gaps, verified fix plans ready for /gsd-execute-phase + + + +@$HOME/.config/opencode/get-shit-done/workflows/verify-work.md +@$HOME/.config/opencode/get-shit-done/templates/UAT.md + + + +Phase: $ARGUMENTS (optional) +- If provided: Test specific phase (e.g., "4") +- If not provided: Check for active sessions or prompt for phase + +Context files are resolved inside the workflow (`init verify-work`) and delegated via `` blocks. + + + +Execute the verify-work workflow from @$HOME/.config/opencode/get-shit-done/workflows/verify-work.md end-to-end. +Preserve all workflow gates (session management, test presentation, diagnosis, fix planning, routing). + diff --git a/original/get-shit-done b/original/get-shit-done index 2eaed7a..0fde35a 160000 --- a/original/get-shit-done +++ b/original/get-shit-done @@ -1 +1 @@ -Subproject commit 2eaed7a8475839958f9ec76ca4c26d9a0bbfc33f +Subproject commit 0fde35acf9509b4484b20a48262ad8ddd3fe7d44