golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

feat(references): add shared behavioral docs and wire into workflows (#1658)

Browse Source 
Add 6 shared reference docs that standardize agent behavior across all
GSD workflows:

- universal-anti-patterns.md: 27 behavioral rules across 8 categories
- context-budget.md: 4-tier system (PEAK/GOOD/DEGRADING/POOR) with
  read-depth rules based on context window size
- gate-prompts.md: 14 named prompt patterns for decision points
- revision-loop.md: Check-Revise-Escalate with stall detection (max 3)
- domain-probes.md: domain-specific follow-up questions for 10 domains
- agent-contracts.md: completion markers for all 21 GSD agents

Wire into existing workflows via @-reference includes:
- plan-phase.md: revision-loop, gate-prompts, agent-contracts
- execute-phase.md: agent-contracts, context-budget
- discuss-phase.md: domain-probes, gate-prompts, universal-anti-patterns
This commit is contained in:
Rezolv
2026-04-04 14:16:27 -04:00
committed by GitHub
parent 840b9981d9
commit 9bf9fc295d
9 changed files with 520 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
get-shit-done/references/agent-contracts.md Normal file
View File

@@ -0,0 +1,79 @@
# Agent Contracts
Completion markers and handoff schemas for all GSD agents. Workflows use these markers to detect agent completion and route accordingly.
This doc describes what IS, not what should be. Casing inconsistencies are documented as they appear in agent source files.
---
## Agent Registry
| Agent | Role | Completion Markers |
|-------|------|--------------------|
| gsd-planner | Plan creation | `## PLANNING COMPLETE` |
| gsd-executor | Plan execution | `## PLAN COMPLETE`, `## CHECKPOINT REACHED` |
| gsd-phase-researcher | Phase-scoped research | `## RESEARCH COMPLETE`, `## RESEARCH BLOCKED` |
| gsd-project-researcher | Project-wide research | `## RESEARCH COMPLETE`, `## RESEARCH BLOCKED` |
| gsd-plan-checker | Plan validation | `## VERIFICATION PASSED`, `## ISSUES FOUND` |
| gsd-research-synthesizer | Multi-research synthesis | `## SYNTHESIS COMPLETE`, `## SYNTHESIS BLOCKED` |
| gsd-debugger | Debug investigation | `## DEBUG COMPLETE`, `## ROOT CAUSE FOUND`, `## CHECKPOINT REACHED` |
| gsd-roadmapper | Roadmap creation/revision | `## ROADMAP CREATED`, `## ROADMAP REVISED`, `## ROADMAP BLOCKED` |
| gsd-ui-auditor | UI review | `## UI REVIEW COMPLETE` |
| gsd-ui-checker | UI validation | `## ISSUES FOUND` |
| gsd-ui-researcher | UI spec creation | `## UI-SPEC COMPLETE`, `## UI-SPEC BLOCKED` |
| gsd-verifier | Post-execution verification | `## Verification Complete` (title case) |
| gsd-integration-checker | Cross-phase integration check | `## Integration Check Complete` (title case) |
| gsd-nyquist-auditor | Sampling audit | `## PARTIAL`, `## ESCALATE` (non-standard) |
| gsd-security-auditor | Security audit | `## OPEN_THREATS`, `## ESCALATE` (non-standard) |
| gsd-codebase-mapper | Codebase analysis | No marker (writes docs directly) |
| gsd-assumptions-analyzer | Assumption extraction | No marker (returns `## Assumptions` sections) |
| gsd-doc-verifier | Doc validation | No marker (writes JSON to `.planning/tmp/`) |
| gsd-doc-writer | Doc generation | No marker (writes docs directly) |
| gsd-advisor-researcher | Advisory research | No marker (utility agent) |
| gsd-user-profiler | User profiling | No marker (returns JSON in analysis tags) |
| gsd-intel-updater | Codebase intelligence analysis | `## INTEL UPDATE COMPLETE`, `## INTEL UPDATE FAILED` |
## Marker Rules
1. **ALL-CAPS markers** (e.g., `## PLANNING COMPLETE`) are the standard convention
2. **Title-case markers** (e.g., `## Verification Complete`) exist in gsd-verifier and gsd-integration-checker -- these are intentional as-is, not bugs
3. **Non-standard markers** (e.g., `## PARTIAL`, `## ESCALATE`) in audit agents indicate partial results requiring orchestrator judgment
4. **Agents without markers** either write artifacts directly to disk or return structured data (JSON/sections) that the caller parses
5. Markers must appear as H2 headings (`## `) at the start of a line in the agent's final output
## Key Handoff Contracts
### Planner -> Executor (via PLAN.md)
| Field | Required | Description |
|-------|----------|-------------|
| Frontmatter | Yes | phase, plan, type, wave, depends_on, files_modified, autonomous, requirements |
| `<objective>` | Yes | What the plan achieves |
| `<tasks>` | Yes | Ordered task list with type, files, action, verify, acceptance_criteria |
| `<verification>` | Yes | Overall verification steps |
| `<success_criteria>` | Yes | Measurable completion criteria |
### Executor -> Verifier (via SUMMARY.md)
| Field | Required | Description |
|-------|----------|-------------|
| Frontmatter | Yes | phase, plan, subsystem, tags, key-files, metrics |
| Commits table | Yes | Per-task commit hashes and descriptions |
| Deviations section | Yes | Auto-fixed issues or "None" |
| Self-Check | Yes | PASSED or FAILED with details |
## Workflow Regex Patterns
Workflows match these markers to detect agent completion:
**plan-phase.md matches:**
- `## RESEARCH COMPLETE` / `## RESEARCH BLOCKED` (researcher output)
- `## PLANNING COMPLETE` (planner output)
- `## CHECKPOINT REACHED` (planner/executor pause)
- `## VERIFICATION PASSED` / `## ISSUES FOUND` (plan-checker output)
**execute-phase.md matches:**
- `## PHASE COMPLETE` (all plans in phase done)
- `## Self-Check: FAILED` (summary self-check)
> **NOTE:** `## PLAN COMPLETE` is the gsd-executor's completion marker but execute-phase.md does not regex-match it. Instead, it detects executor completion via spot-checks (SUMMARY.md existence, git commit state). This is intentional behavior, not a mismatch.

49
get-shit-done/references/context-budget.md Normal file
View File

@@ -0,0 +1,49 @@
# Context Budget Rules
Standard rules for keeping orchestrator context lean. Reference this in workflows that spawn subagents or read significant content.
See also: `references/universal-anti-patterns.md` for the complete set of universal rules.
---
## Universal Rules
Every workflow that spawns agents or reads significant content must follow these rules:
1. **Never** read agent definition files (`agents/*.md`) -- `subagent_type` auto-loads them
2. **Never** inline large files into subagent prompts -- tell agents to read files from disk instead
3. **Read depth scales with context window** -- check `context_window_tokens` in `.planning/config.json`:
- At < 500000 tokens (default 200k): read only frontmatter, status fields, or summaries. Never read full SUMMARY.md, VERIFICATION.md, or RESEARCH.md bodies.
- At >= 500000 tokens (1M model): MAY read full subagent output bodies when the content is needed for inline presentation or decision-making. Still avoid unnecessary reads.
4. **Delegate** heavy work to subagents -- the orchestrator routes, it doesn't execute
5. **Proactive warning**: If you've already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider checkpointing progress."
## Read Depth by Context Window
| Context Window | Subagent Output Reading | SUMMARY.md | VERIFICATION.md | PLAN.md (other phases) |
|---------------|------------------------|------------|-----------------|------------------------|
| < 500k (200k model) | Frontmatter only | Frontmatter only | Frontmatter only | Current phase only |
| >= 500k (1M model) | Full body permitted | Full body permitted | Full body permitted | Current phase only |
**How to check:** Read `.planning/config.json` and inspect `context_window_tokens`. If the field is absent, treat as 200k (conservative default).
## Context Degradation Tiers
Monitor context usage and adjust behavior accordingly:
| Tier | Usage | Behavior |
|------|-------|----------|
| PEAK | 0-30% | Full operations. Read bodies, spawn multiple agents, inline results. |
| GOOD | 30-50% | Normal operations. Prefer frontmatter reads, delegate aggressively. |
| DEGRADING | 50-70% | Economize. Frontmatter-only reads, minimal inlining, warn user about budget. |
| POOR | 70%+ | Emergency mode. Checkpoint progress immediately. No new reads unless critical. |
## Context Degradation Warning Signs
Quality degrades gradually before panic thresholds fire. Watch for these early signals:
- **Silent partial completion** -- agent claims task is done but implementation is incomplete. Self-check catches file existence but not semantic completeness. Always verify agent output meets the plan's must_haves, not just that files exist.
- **Increasing vagueness** -- agent starts using phrases like "appropriate handling" or "standard patterns" instead of specific code. This indicates context pressure even before budget warnings fire.
- **Skipped steps** -- agent omits protocol steps it would normally follow. If an agent's success criteria has 8 items but it only reports 5, suspect context pressure.
When delegating to agents, the orchestrator cannot verify semantic correctness of agent output -- only structural completeness. This is a fundamental limitation. Mitigate with must_haves.truths and spot-check verification.

125
get-shit-done/references/domain-probes.md Normal file
View File

@@ -0,0 +1,125 @@
# Domain-Aware Probing Patterns
Shared reference for `/gsd-begin`, `/gsd-discuss-phase`, and domain exploration workflows.
When the user mentions a technology area, use these probes to ask insightful follow-up questions. Don't run through them as a checklist -- pick the 2-3 most relevant based on context. The goal is to surface hidden assumptions and trade-offs the user may not have considered yet.
---
## Authentication
| User mentions | Agent probes with domain knowledge |
|---|---|
| "login" or "auth" | OAuth (which providers?), JWT, or session-based? Do you need social login or just email/password? |
| "users" or "accounts" | MFA required? Password reset flow? Email verification? |
| "sessions" | Session duration and refresh strategy? Server-side sessions or stateless tokens? |
| "roles" or "permissions" | RBAC, ABAC, or simple role checks? How many distinct roles? |
| "API keys" | Key rotation strategy? Scoped permissions per key? Rate limiting per key? |
---
## Real-Time Updates
| User mentions | Agent probes with domain knowledge |
|---|---|
| "real-time" or "live updates" | WebSockets, SSE, or polling? What specifically needs to be real-time vs. eventual? |
| "notifications" | Push notifications (browser/mobile), in-app only, or both? Persistence and read receipts? |
| "collaboration" or "multiplayer" | Conflict resolution strategy? Operational transforms or CRDTs? Expected concurrent users? |
| "chat" or "messaging" | Message history and search? Typing indicators? Read receipts? |
| "streaming" | Reconnection strategy? What happens when the connection drops -- queue or discard? |
---
## Dashboard
| User mentions | Agent probes with domain knowledge |
|---|---|
| "dashboard" | What data sources feed it? How many distinct views? |
| "charts" or "graphs" | Interactive or static? Drill-down capability? Export to CSV/PDF? |
| "metrics" or "KPIs" | Refresh strategy -- real-time, periodic polling, or on-demand? Acceptable staleness? |
| "admin panel" | Role-based visibility? Which actions beyond viewing (edit, delete, approve)? |
| "mobile" or "responsive" | Simplified mobile view or full parity? Touch interactions for charts? |
---
## API Design
| User mentions | Agent probes with domain knowledge |
|---|---|
| "API" | REST, GraphQL, or RPC-style? Internal only or public-facing? |
| "endpoints" or "routes" | Versioning strategy (URL path, header, query param)? Breaking change policy? |
| "pagination" | Cursor-based or offset? Expected result set sizes? Stable ordering guarantee? |
| "rate limiting" | Per-user, per-IP, or per-API-key? Burst allowance? How to communicate limits to clients? |
| "errors" | Structured error format? Error codes vs. messages? How much detail in production errors? |
---
## Database
| User mentions | Agent probes with domain knowledge |
|---|---|
| "database" or "storage" | SQL or NoSQL? What drives the choice -- relational integrity, flexibility, scale? |
| "ORM" or "queries" | ORM (which one?) or raw queries? Query builder as middle ground? |
| "migrations" | Migration tool? Rollback strategy? How do you handle data migrations vs. schema migrations? |
| "seeding" or "test data" | Seed data for development? Realistic fake data or minimal fixtures? |
| "scale" or "performance" | Read/write ratio? Read replicas? Connection pooling strategy? |
---
## Search
| User mentions | Agent probes with domain knowledge |
|---|---|
| "search" | Full-text or exact match? Dedicated search engine (Elasticsearch, Meilisearch) or database-level? |
| "filtering" or "facets" | Faceted filtering? How many filter dimensions? Combined filters (AND/OR)? |
| "autocomplete" or "typeahead" | Debounce strategy? Minimum character threshold? Result ranking? |
| "indexing" | Index size and update frequency? Real-time indexing or batch? Acceptable index lag? |
| "fuzzy" or "typo tolerance" | Fuzzy matching? Synonym support? Language-specific stemming? |
---
## File Upload/Storage
| User mentions | Agent probes with domain knowledge |
|---|---|
| "upload" or "file upload" | Local filesystem or cloud (S3, GCS, Azure Blob)? Direct upload or through server? |
| "images" or "media" | Processing pipeline -- resize, compress, thumbnail generation? Format conversion? |
| "size limits" | Max file size? Max total storage per user? What happens when limits are hit? |
| "CDN" | CDN for delivery? Cache invalidation for updated files? Signed URLs for access control? |
| "documents" or "attachments" | Virus scanning? Preview generation? Versioning of uploaded files? |
---
## Caching
| User mentions | Agent probes with domain knowledge |
|---|---|
| "caching" or "performance" | Where to cache -- browser, CDN, application layer, database query cache? |
| "invalidation" | Invalidation strategy -- TTL, event-driven, or manual? Cache-aside vs. write-through? |
| "stale data" | Acceptable staleness window? Stale-while-revalidate pattern? |
| "Redis" or "Memcached" | Cache topology -- single node or clustered? Persistence needed or pure cache? |
| "CDN" or "edge" | Edge caching for static assets? Dynamic content at the edge? Cache key strategy? |
---
## Testing
| User mentions | Agent probes with domain knowledge |
|---|---|
| "testing" or "tests" | Unit, integration, and E2E balance? Where do you invest most testing effort? |
| "mocking" or "stubs" | Mock external services or use test containers? Database mocking strategy? |
| "CI" or "pipeline" | Tests in CI? Parallel test execution? Test-on-PR or test-on-push? |
| "coverage" | Coverage targets? Coverage as gate or advisory? Which metrics (line, branch, function)? |
| "E2E" or "browser testing" | Playwright, Cypress, or other? Headed vs. headless? Visual regression testing? |
---
## Deployment
| User mentions | Agent probes with domain knowledge |
|---|---|
| "deploy" or "hosting" | Container, serverless, or traditional VM/VPS? Managed platform (Vercel, Railway) or self-hosted? |
| "CI/CD" or "pipeline" | GitHub Actions, GitLab CI, or other? Deploy on merge to main or manual trigger? |
| "environments" | How many environments (dev, staging, prod)? Environment parity strategy? |
| "rollback" | Rollback strategy? Blue-green, canary, or instant rollback? Database rollback considerations? |
| "secrets" or "config" | Secret management -- env vars, vault, or platform-native? Per-environment config strategy? |

100
get-shit-done/references/gate-prompts.md Normal file
View File

@@ -0,0 +1,100 @@
# Gate Prompt Patterns
Reusable prompt patterns for structured gate checks in workflows and agents.
**For checkpoint box format details, see `references/ui-brand.md`** -- checkpoint boxes use double-line border drawing with 62-character inner width.
## Rules
- `header` must be max 12 characters
- `multiSelect` is always `false` for gate checks
- Always handle the "Other" case (user typed a freeform response instead of selecting)
- Max 4 options per prompt -- if more are needed, use a 2-step flow
---
## Pattern: approve-revise-abort
3-option gate for plan approval, gap-closure approval.
- question: "Approve these {noun}?"
- header: "Approve?"
- options: Approve | Request changes | Abort
## Pattern: yes-no
Simple 2-option confirmation for re-planning, rebuild, replace plans, commit.
- question: "{Specific question about the action}"
- header: "Confirm"
- options: Yes | No
## Pattern: stale-continue
2-option refresh gate for staleness warnings, timestamp freshness.
- question: "{Artifact} may be outdated. Refresh or continue?"
- header: "Stale"
- options: Refresh | Continue anyway
## Pattern: yes-no-pick
3-option selection for seed selection, item inclusion.
- question: "Include {items} in planning?"
- header: "Include?"
- options: Yes, all | Let me pick | No
## Pattern: multi-option-failure
4-option failure handler for build failures.
- question: "Plan {id} failed. How should we proceed?"
- header: "Failed"
- options: Retry | Skip | Rollback | Abort
## Pattern: multi-option-escalation
4-option escalation for review escalation (max retries exceeded).
- question: "Phase {N} has failed verification {attempt} times. How should we proceed?"
- header: "Escalate"
- options: Accept gaps | Re-plan (via /gsd-plan-phase) | Debug (via /gsd-debug) | Retry
## Pattern: multi-option-gaps
4-option gap handler for review gaps-found.
- question: "{count} verification gaps need attention. How should we proceed?"
- header: "Gaps"
- options: Auto-fix | Override | Manual | Skip
## Pattern: multi-option-priority
4-option priority selection for milestone gap priority.
- question: "Which gaps should we address?"
- header: "Priority"
- options: Must-fix only | Must + should | Everything | Let me pick
## Pattern: toggle-confirm
2-option confirmation for enabling/disabling boolean features.
- question: "Enable {feature_name}?"
- header: "Toggle"
- options: Enable | Disable
## Pattern: action-routing
Up to 4 suggested next actions with selection (status, resume workflows).
- question: "What would you like to do next?"
- header: "Next Step"
- options: {primary action} | {alternative 1} | {alternative 2} | Something else
- Note: Dynamically generate options from workflow state. Always include "Something else" as last option.
## Pattern: scope-confirm
3-option confirmation for quick task scope validation.
- question: "This task looks complex. Proceed as quick task or use full planning?"
- header: "Scope"
- options: Quick task | Full plan (via /gsd-plan-phase) | Revise
## Pattern: depth-select
3-option depth selection for planning workflow preferences.
- question: "How thorough should planning be?"
- header: "Depth"
- options: Quick (3-5 phases, skip research) | Standard (5-8 phases, default) | Comprehensive (8-12 phases, deep research)
## Pattern: context-handling
3-option handler for existing CONTEXT.md in discuss workflow.
- question: "Phase {N} already has a CONTEXT.md. How should we handle it?"
- header: "Context"
- options: Overwrite | Append | Cancel
## Pattern: gray-area-option
Dynamic template for presenting gray area choices in discuss workflow.
- question: "{Gray area title}"
- header: "Decision"
- options: {Option 1} | {Option 2} | Let Claude decide
- Note: Options generated at runtime. Always include "Let Claude decide" as last option.

97
get-shit-done/references/revision-loop.md Normal file
View File

@@ -0,0 +1,97 @@
# Revision Loop Pattern
Standard pattern for iterative agent revision with feedback. Used when a checker/validator finds issues and the producing agent needs to revise its output.
---
## Pattern: Check-Revise-Escalate (max 3 iterations)
This pattern applies whenever:
1. An agent produces output (plans, imports, gap-closure plans)
2. A checker/validator evaluates that output
3. Issues are found that need revision
### Flow
```
prev_issue_count = Infinity
iteration = 0
LOOP:
1. Run checker/validator on current output
2. Read checker results
3. If PASSED or only INFO-level issues:
-> Accept output, exit loop
4. If BLOCKER or WARNING issues found:
a. iteration += 1
b. If iteration > 3:
-> Escalate to user (see "After 3 Iterations" below)
c. Parse issue count from checker output
d. If issue_count >= prev_issue_count:
-> Escalate to user: "Revision loop stalled (issue count not decreasing)"
e. prev_issue_count = issue_count
f. Re-spawn the producing agent with checker feedback appended
g. After revision completes, go to LOOP
```
### Issue Count Tracking
Track the number of BLOCKER + WARNING issues returned by the checker on each iteration. If the count does not decrease between consecutive iterations, the producing agent is stuck and further iterations will not help. Break early and escalate to the user.
Display iteration progress before each revision spawn:
`Revision iteration {N}/3 -- {blocker_count} blockers, {warning_count} warnings`
### Re-spawn Prompt Structure
When re-spawning the producing agent for revision, pass the checker's YAML-formatted issues. The checker's output contains a `## Issues` heading followed by a YAML block. Parse this block and pass it verbatim to the revision agent.
```
<checker_issues>
The issues below are in YAML format. Each has: dimension, severity, finding,
affected_field, suggested_fix. Address ALL BLOCKER issues. Address WARNING
issues where feasible.
{YAML issues block from checker output -- passed verbatim}
</checker_issues>
<revision_instructions>
Address ALL BLOCKER and WARNING issues identified above.
- For each BLOCKER: make the required change
- For each WARNING: address or explain why it's acceptable
- Do NOT introduce new issues while fixing existing ones
- Preserve all content not flagged by the checker
This is revision iteration {N} of max 3. Previous iteration had {prev_count}
issues. You must reduce the count or the loop will terminate.
</revision_instructions>
```
### After 3 Iterations
If issues persist after 3 revision cycles:
1. Present remaining issues to the user
2. Use gate prompt (pattern: yes-no from `references/gate-prompts.md`):
question: "Issues remain after 3 revision attempts. Proceed with current output?"
header: "Proceed?"
options:
- label: "Proceed anyway" description: "Accept output with remaining issues"
- label: "Adjust approach" description: "Discuss a different approach"
3. If "Proceed anyway": accept current output and continue
4. If "Adjust approach" or "Other": discuss with user, then re-enter the producing step with updated context
### Workflow-Specific Variations
| Workflow | Producer Agent | Checker Agent | Notes |
|----------|---------------|---------------|-------|
| plan-phase | gsd-planner | gsd-plan-checker | Revision prompt via planner-revision.md |
| execute-phase | gsd-executor | gsd-verifier | Post-execution verification |
| discuss-phase | orchestrator | gsd-plan-checker | Inline revision by orchestrator |
---
## Important Notes
- **INFO-level issues are always acceptable** -- they don't trigger revision
- **Each iteration gets a fresh agent spawn** -- don't try to continue in the same context
- **Checker feedback must be inlined** -- the revision agent needs to see exactly what failed
- **Don't silently swallow issues** -- always present the final state to the user after exiting the loop

58
get-shit-done/references/universal-anti-patterns.md Normal file
View File

@@ -0,0 +1,58 @@
# Universal Anti-Patterns
Rules that apply to ALL workflows and agents. Individual workflows may have additional specific anti-patterns.
---
## Context Budget Rules
1. **Never** read agent definition files (`agents/*.md`) -- `subagent_type` auto-loads them. Reading agent definitions into the orchestrator wastes context for content automatically injected into subagent sessions.
2. **Never** inline large files into subagent prompts -- tell agents to read files from disk instead. Agents have their own context windows.
3. **Read depth scales with context window** -- check `context_window_tokens` in `.planning/config.json`. At < 500000: read only frontmatter, status fields, or summaries. At >= 500000 (1M model): full body reads permitted when content is needed for inline decisions. See `references/context-budget.md` for the complete table.
4. **Delegate** heavy work to subagents -- the orchestrator routes, it does not build, analyze, research, investigate, or verify.
5. **Proactive pause warning**: If you have already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider checkpointing progress."
## File Reading Rules
6. **SUMMARY.md read depth scales with context window** -- at context_window_tokens < 500000: read frontmatter only from prior phase SUMMARYs. At >= 500000: full body reads permitted for direct-dependency phases. Transitive dependencies (2+ phases back) remain frontmatter-only regardless.
7. **Never** read full PLAN.md files from other phases -- only current phase plans.
8. **Never** read `.planning/logs/` files -- only the health workflow reads these.
9. **Do not** re-read full file contents when frontmatter is sufficient -- frontmatter contains status, key_files, commits, and provides fields. Exception: at >= 500000, re-reading full body is acceptable when semantic content is needed.
## Subagent Rules
10. **NEVER** use non-GSD agent types (`general-purpose`, `Explore`, `Plan`, `Bash`, `feature-dev`, etc.) -- ALWAYS use `subagent_type: "gsd-{agent}"` (e.g., `gsd-phase-researcher`, `gsd-executor`, `gsd-planner`). GSD agents have project-aware prompts, audit logging, and workflow context. Generic agents bypass all of this.
11. **Do not** re-litigate decisions that are already locked in CONTEXT.md (or PROJECT.md ## Context section) -- respect locked decisions unconditionally.
## Questioning Anti-Patterns
Reference: `references/questioning.md` for the full anti-pattern list.
12. **Do not** walk through checklists -- checklist walking (asking items one by one from a list) is the #1 anti-pattern. Instead, use progressive depth: start broad, dig where interesting.
13. **Do not** use corporate speak -- avoid jargon like "stakeholder alignment", "synergize", "deliverables". Use plain language.
14. **Do not** apply premature constraints -- don't narrow the solution space before understanding the problem. Ask about the problem first, then constrain.
## State Management Anti-Patterns
15. **No direct Write/Edit to STATE.md or ROADMAP.md for mutations.** Always use `gsd-tools.cjs` CLI commands (`state update`, `state advance-plan`, `roadmap update-status`) for mutations. Direct Write tool usage bypasses safe update logic and is unsafe in multi-session environments. Exception: first-time creation of STATE.md from template is allowed.
## Behavioral Rules
16. **Do not** create artifacts the user did not approve -- always confirm before writing new planning documents.
17. **Do not** modify files outside the workflow's stated scope -- check the plan's files_modified list.
18. **Do not** suggest multiple next actions without clear priority -- one primary suggestion, alternatives listed secondary.
19. **Do not** use `git add .` or `git add -A` -- stage specific files only.
20. **Do not** include sensitive information (API keys, passwords, tokens) in planning documents or commits.
## Error Recovery Rules
21. **Git lock detection**: Before any git operation, if it fails with "Unable to create lock file", check for stale `.git/index.lock` and advise the user to remove it (do not remove automatically).
22. **Config fallback awareness**: Config loading returns `null` silently on invalid JSON. If your workflow depends on config values, check for null and warn the user: "config.json is invalid or missing -- running with defaults."
23. **Partial state recovery**: If STATE.md references a phase directory that doesn't exist, do not proceed silently. Warn the user and suggest diagnosing the mismatch.
## GSD-Specific Rules
24. **Do not** check for `mode === 'auto'` or `mode === 'autonomous'` -- GSD uses `yolo` config flag. Check `yolo: true` for autonomous mode, absence or `false` for interactive mode.
25. **Always use `gsd-tools.cjs`** (not `gsd-tools.js` or any other variant) -- GSD uses CommonJS for Node.js CLI compatibility.
26. **Plan files MUST follow `{padded_phase}-{NN}-PLAN.md` pattern** (e.g., `01-01-PLAN.md`). Never use `PLAN-01.md`, `plan-01.md`, or any other variation -- gsd-tools detection depends on this exact pattern.
27. **Do not start executing the next plan before writing the SUMMARY.md for the current plan** -- downstream plans may reference it via `@` includes.

6
get-shit-done/workflows/discuss-phase.md
View File

@@ -4,6 +4,12 @@ Extract implementation decisions that downstream agents need. Analyze the phase
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.
</purpose>
<required_reading>
@~/.claude/get-shit-done/references/domain-probes.md
@~/.claude/get-shit-done/references/gate-prompts.md
@~/.claude/get-shit-done/references/universal-anti-patterns.md
</required_reading>
<downstream_awareness>
**CONTEXT.md feeds into:**

3
get-shit-done/workflows/execute-phase.md
View File

@@ -25,6 +25,9 @@ via filesystem and git state.
<required_reading>
Read STATE.md before any operation to load project context.
@~/.claude/get-shit-done/references/agent-contracts.md
@~/.claude/get-shit-done/references/context-budget.md
</required_reading>
<available_agent_types>

3
get-shit-done/workflows/plan-phase.md
View File

@@ -6,6 +6,9 @@ Create executable phase prompts (PLAN.md files) for a roadmap phase with integra
Read all files referenced by the invoking prompt's execution_context before starting.
@~/.claude/get-shit-done/references/ui-brand.md
@~/.claude/get-shit-done/references/revision-loop.md
@~/.claude/get-shit-done/references/gate-prompts.md
@~/.claude/get-shit-done/references/agent-contracts.md
</required_reading>
<available_agent_types>