pmp-gywd 3.3.0

package/get-your-work-done/references/checkpoints.md

@@ -0,0 +1,287 @@
+<overview>
+Plans execute autonomously. Checkpoints formalize interaction points where human verification or decisions are needed.
+
+**Core principle:** Claude automates everything with CLI/API. Checkpoints are for verification and decisions, not manual work.
+</overview>
+
+<checkpoint_types>
+
+## checkpoint:human-verify (90% of checkpoints)
+
+**When:** Claude completed automated work, human confirms it works correctly.
+
+**Use for:** Visual UI checks, interactive flows, functional verification, audio/video quality, animation smoothness, accessibility testing.
+
+**Structure:**
+```xml
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>[What Claude automated]</what-built>
+  <how-to-verify>[Numbered steps - URLs, commands, expected behavior]</how-to-verify>
+  <resume-signal>[How to continue - "approved" or describe issues]</resume-signal>
+</task>
+```
+
+**Example:**
+```xml
+<task type="auto">
+  <name>Deploy to Vercel</name>
+  <action>Run `vercel --yes` to deploy. Capture URL.</action>
+  <verify>vercel ls shows deployment, curl {url} returns 200</verify>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>Deployed to https://myapp.vercel.app</what-built>
+  <how-to-verify>
+    Visit URL and confirm:
+    1. Homepage loads without errors
+    2. All images/assets load
+    3. No console errors
+  </how-to-verify>
+  <resume-signal>Type "approved" or describe issues</resume-signal>
+</task>
+```
+
+## checkpoint:decision (9% of checkpoints)
+
+**When:** Human must make choice that affects implementation direction.
+
+**Use for:** Technology selection, architecture decisions, design choices, feature prioritization.
+
+**Structure:**
+```xml
+<task type="checkpoint:decision" gate="blocking">
+  <decision>[What's being decided]</decision>
+  <context>[Why this matters]</context>
+  <options>
+    <option id="option-a"><name>[Name]</name><pros>[Benefits]</pros><cons>[Tradeoffs]</cons></option>
+    <option id="option-b"><name>[Name]</name><pros>[Benefits]</pros><cons>[Tradeoffs]</cons></option>
+  </options>
+  <resume-signal>[How to indicate choice]</resume-signal>
+</task>
+```
+
+**Example:**
+```xml
+<task type="checkpoint:decision" gate="blocking">
+  <decision>Select authentication provider</decision>
+  <context>Need user auth. Three options with different tradeoffs.</context>
+  <options>
+    <option id="supabase"><name>Supabase Auth</name><pros>Built-in with DB, free tier, RLS integration</pros><cons>Less customizable, ecosystem lock-in</cons></option>
+    <option id="clerk"><name>Clerk</name><pros>Beautiful UI, best DX</pros><cons>Paid after 10k MAU</cons></option>
+    <option id="nextauth"><name>NextAuth.js</name><pros>Free, self-hosted, max control</pros><cons>More setup, DIY security</cons></option>
+  </options>
+  <resume-signal>Select: supabase, clerk, or nextauth</resume-signal>
+</task>
+```
+
+## checkpoint:human-action (1% - rare)
+
+**When:** Action has NO CLI/API and requires human-only interaction.
+
+**Use ONLY for:** Email verification links, SMS 2FA codes, manual account approvals, 3D Secure payment flows, OAuth app approvals.
+
+**Do NOT use for:** Deployments (use CLI), creating resources (use CLI/API), builds/tests (use Bash), file operations (use Write/Edit).
+
+**Structure:**
+```xml
+<task type="checkpoint:human-action" gate="blocking">
+  <action>[Unavoidable manual step]</action>
+  <instructions>[What Claude automated] [ONE thing requiring human action]</instructions>
+  <verification>[What Claude checks afterward]</verification>
+  <resume-signal>[How to continue]</resume-signal>
+</task>
+```
+
+**Example (email verification):**
+```xml
+<task type="checkpoint:human-action" gate="blocking">
+  <action>Complete email verification for SendGrid account</action>
+  <instructions>
+    I created the account and requested verification email.
+    Check your inbox for verification link and click it.
+  </instructions>
+  <verification>SendGrid API key works: curl test succeeds</verification>
+  <resume-signal>Type "done" when verified</resume-signal>
+</task>
+```
+
+</checkpoint_types>
+
+<execution_protocol>
+
+When Claude encounters `type="checkpoint:*"`:
+
+1. **Stop immediately** - do not proceed to next task
+2. **Display checkpoint clearly:**
+
+```
+════════════════════════════════════════
+CHECKPOINT: [Type]
+════════════════════════════════════════
+
+Task [X] of [Y]: [Name]
+
+[Checkpoint-specific content]
+
+[Resume signal instruction]
+════════════════════════════════════════
+```
+
+3. **Wait for user response** - do not hallucinate completion
+4. **Verify if possible** - check files, run tests
+5. **Resume execution** - continue only after confirmation
+
+</execution_protocol>
+
+<authentication_gates>
+
+**Critical:** When Claude tries CLI/API and gets auth error, this is NOT a failure - it's a gate requiring human input to unblock automation.
+
+**Pattern:** Claude tries automation → auth error → creates checkpoint → you authenticate → Claude retries → continues
+
+**Gate protocol:**
+1. Recognize it's not a failure - missing auth is expected
+2. Stop current task - don't retry repeatedly
+3. Create checkpoint:human-action dynamically
+4. Provide exact authentication steps
+5. Verify authentication works
+6. Retry the original task
+7. Continue normally
+
+**Example (Vercel auth gate):**
+```xml
+<!-- Claude tries to deploy -->
+<task type="auto">
+  <name>Deploy to Vercel</name>
+  <action>Run `vercel --yes` to deploy</action>
+</task>
+
+<!-- If vercel returns "Error: Not authenticated" -->
+<task type="checkpoint:human-action" gate="blocking">
+  <action>Authenticate Vercel CLI so I can continue</action>
+  <instructions>
+    I tried to deploy but got authentication error.
+    Run: vercel login (opens browser)
+  </instructions>
+  <verification>vercel whoami returns your account</verification>
+  <resume-signal>Type "done" when authenticated</resume-signal>
+</task>
+
+<!-- After auth, Claude retries automatically -->
+<task type="auto">
+  <name>Retry deployment</name>
+  <action>Run `vercel --yes` (now authenticated)</action>
+</task>
+```
+
+**Key distinction:**
+- Pre-planned checkpoint: "I need you to do X" (wrong - Claude should automate)
+- Auth gate: "I tried to automate X but need credentials" (correct - unblocks automation)
+
+</authentication_gates>
+
+<automation_reference>
+
+**The rule:** If it has CLI/API, Claude does it. Never ask human to perform automatable work.
+
+| Service | CLI/API | Key Commands | Auth Gate |
+|---------|---------|--------------|-----------|
+| 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 calls | API key in .env |
+| 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` | N/A |
+| Xcode | `xcodebuild` | `-project`, `-scheme`, `build`, `test` | N/A |
+
+**Env files:** Use Write/Edit tools. Never ask human to create .env manually.
+
+**Quick reference:**
+
+| Action | Automatable? | Claude does it? |
+|--------|--------------|-----------------|
+| Deploy to Vercel | Yes (`vercel`) | YES |
+| Create Stripe webhook | Yes (API) | YES |
+| Write .env file | Yes (Write tool) | YES |
+| Create Upstash DB | Yes (`upstash`) | YES |
+| Run tests | Yes (`npm test`) | YES |
+| Click email verification link | No | NO |
+| Enter credit card with 3DS | No | NO |
+
+</automation_reference>
+
+<guidelines>
+
+**DO:**
+- Automate everything with CLI/API before checkpoint
+- Be specific: "Visit https://myapp.vercel.app" not "check deployment"
+- Number verification steps
+- State expected outcomes
+- Make verification executable
+
+**DON'T:**
+- Ask human to do work Claude can automate
+- Assume knowledge: "Configure the usual settings"
+- Mix multiple verifications in one checkpoint
+- Use checkpoints too frequently (verification fatigue)
+
+**Placement:**
+- After automation completes (not before)
+- After UI buildout
+- Before dependent work (decisions)
+- At integration points
+
+</guidelines>
+
+<anti_patterns>
+
+**BAD: Asking human to automate**
+```xml
+<task type="checkpoint:human-action">
+  <action>Deploy to Vercel</action>
+  <instructions>Visit vercel.com/new, import repo, click Deploy</instructions>
+</task>
+```
+Why bad: Vercel has CLI. Use `vercel --yes`.
+
+**BAD: Too many checkpoints**
+```xml
+<task type="auto">Create schema</task>
+<task type="checkpoint:human-verify">Check schema</task>
+<task type="auto">Create API</task>
+<task type="checkpoint:human-verify">Check API</task>
+```
+Why bad: Verification fatigue. Combine into one checkpoint at end.
+
+**GOOD: Claude automates, human verifies once**
+```xml
+<task type="auto">Create schema</task>
+<task type="auto">Create API</task>
+<task type="auto">Create UI</task>
+
+<task type="checkpoint:human-verify">
+  <what-built>Complete auth flow</what-built>
+  <how-to-verify>Test full flow: register, login, access protected page</how-to-verify>
+</task>
+```
+
+</anti_patterns>
+
+<summary>
+
+**The golden rule:** If Claude CAN automate it, Claude MUST automate it.
+
+**Checkpoint priority:**
+1. **checkpoint:human-verify** (90%) - Claude automated, human confirms visual/functional correctness
+2. **checkpoint:decision** (9%) - Human makes architectural/technology choices
+3. **checkpoint:human-action** (1%) - Truly unavoidable manual steps with no API/CLI
+
+**When NOT to use checkpoints:**
+- Things Claude can verify programmatically (tests, builds)
+- File operations (Claude can read/write)
+- Anything with CLI/API available
+
+</summary>

package/get-your-work-done/references/confidence-scoring.md

@@ -0,0 +1,169 @@
+# Confidence Scoring Reference
+
+## Overview
+
+Confidence scoring adds transparency to AI decisions by showing certainty levels for plans, tasks, and recommendations. This helps users understand when to trust AI output vs. when to review more carefully.
+
+## Score Scale
+
+| Score | Label | Meaning | User Action |
+|-------|-------|---------|-------------|
+| 95-100% | **Certain** | Well-established pattern, clear requirements | Trust and proceed |
+| 85-94% | **High** | Standard approach, minor ambiguity | Quick review |
+| 70-84% | **Moderate** | Multiple valid approaches, some unknowns | Review recommended |
+| 50-69% | **Low** | Significant uncertainty, assumptions made | Careful review |
+| <50% | **Uncertain** | Guessing, insufficient context | User decision needed |
+
+## When to Apply Scores
+
+### Phase Planning
+
+Each phase should have an overall confidence score:
+
+```markdown
+## Phase 3: Payment Integration
+
+**Confidence: 78%** (Moderate)
+
+Factors:
+- ✅ Clear requirements for Stripe integration
+- ✅ Standard patterns available
+- ⚠️ Webhook handling approach uncertain
+- ⚠️ Refund flow not fully specified
+```
+
+### Task-Level Scoring
+
+Each task in a PLAN.md should include confidence:
+
+```markdown
+### Task 1: Create Stripe client wrapper [92% confidence]
+
+- Standard library usage, well-documented API
+- Similar patterns exist in codebase
+
+### Task 2: Implement webhook handlers [65% confidence]
+
+- Multiple valid approaches (queue vs direct)
+- Error handling strategy unclear
+- May need user input on retry policy
+```
+
+### Decision Points
+
+When plans include decisions, score each option:
+
+```markdown
+## Decision: State Management Approach
+
+| Option | Confidence | Rationale |
+|--------|------------|-----------|
+| Redux Toolkit | 85% | Team familiarity, existing patterns |
+| Zustand | 72% | Simpler, but team hasn't used |
+| React Context | 60% | May not scale for this use case |
+
+Recommendation: Redux Toolkit (85%)
+```
+
+## Confidence Factors
+
+### Increases Confidence (+)
+
+- Clear, specific requirements
+- Existing patterns in codebase
+- Well-documented libraries/APIs
+- Similar past implementations
+- Strong test coverage exists
+- Team has relevant experience
+
+### Decreases Confidence (-)
+
+- Vague or missing requirements
+- Novel/unusual approach
+- Undocumented or experimental tech
+- No similar implementations
+- External dependencies with unknowns
+- Time pressure compromising research
+
+## Integration with Commands
+
+### /gywd:plan-phase
+
+Plans should include:
+```markdown
+## Plan Confidence Summary
+
+**Overall: 82%** (High)
+
+| Task | Confidence | Flag |
+|------|------------|------|
+| T1 | 95% | - |
+| T2 | 88% | - |
+| T3 | 65% | ⚠️ Review |
+| T4 | 78% | - |
+
+⚠️ Task 3 has low confidence - consider:
+- Breaking into smaller tasks
+- Requesting clarification
+- Adding research step
+```
+
+### /gywd:preview-plan
+
+Show confidence in preview:
+```markdown
+## Risk Assessment
+
+**Plan Confidence: 76%** (Moderate)
+
+Low-confidence tasks:
+- Task 3: Caching strategy (62%) - Multiple valid approaches
+- Task 5: Error handling (68%) - Edge cases unclear
+
+Recommendation: Review tasks 3 and 5 before execution
+```
+
+### /gywd:execute-plan
+
+During execution, flag low-confidence work:
+```
+Executing Task 3... [65% confidence]
+⚠️ Low confidence task - proceeding with stated approach
+   Assumption: Using Redis for caching
+   Alternative considered: In-memory with TTL
+```
+
+## Calculating Confidence
+
+### Automated Factors
+
+1. **Requirement clarity** (0-25 points)
+   - Specific acceptance criteria: +15
+   - Clear inputs/outputs: +10
+
+2. **Pattern availability** (0-25 points)
+   - Existing pattern in codebase: +15
+   - Standard library approach: +10
+
+3. **Complexity assessment** (0-25 points)
+   - Single responsibility: +15
+   - Limited external deps: +10
+
+4. **Context completeness** (0-25 points)
+   - Full codebase context: +15
+   - Recent related work: +10
+
+### Human Override
+
+Users can adjust confidence:
+```
+/gywd:memory add rule "Payment tasks always need review (max 80% confidence)"
+```
+
+## Best Practices
+
+1. **Never hide uncertainty** - If unsure, say so
+2. **Explain factors** - Show what affects the score
+3. **Provide alternatives** - For low-confidence decisions
+4. **Flag for review** - Automatically surface <70% items
+5. **Learn from outcomes** - Adjust future confidence based on results

package/get-your-work-done/references/continuation-format.md

@@ -0,0 +1,255 @@
+# Continuation Format
+
+Standard format for presenting next steps after completing a command or workflow.
+
+## Core Structure
+
+```
+---
+
+## ▶ Next Up
+
+**{identifier}: {name}** — {one-line description}
+
+`{command to copy-paste}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `{alternative option 1}` — description
+- `{alternative option 2}` — description
+
+---
+```
+
+## Format Rules
+
+1. **Always show what it is** — name + description, never just a command path
+2. **Pull context from source** — ROADMAP.md for phases, PLAN.md `<objective>` for plans
+3. **Command in inline code** — backticks, easy to copy-paste, renders as clickable link
+4. **`/clear` explanation** — always include, keeps it concise but explains why
+5. **"Also available" not "Other options"** — sounds more app-like
+6. **Visual separators** — `---` above and below to make it stand out
+
+## Variants
+
+### Execute Next Plan
+
+```
+---
+
+## ▶ Next Up
+
+**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
+
+`/gywd:execute-plan .planning/phases/02-auth/02-03-PLAN.md`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- Review plan before executing
+- `/gywd:list-phase-assumptions 2` — check assumptions
+
+---
+```
+
+### Execute Final Plan in Phase
+
+Add note that this is the last plan and what comes after:
+
+```
+---
+
+## ▶ Next Up
+
+**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
+<sub>Final plan in Phase 2</sub>
+
+`/gywd:execute-plan .planning/phases/02-auth/02-03-PLAN.md`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**After this completes:**
+- Phase 2 → Phase 3 transition
+- Next: **Phase 3: Core Features** — User dashboard and settings
+
+---
+```
+
+### Plan a Phase
+
+```
+---
+
+## ▶ Next Up
+
+**Phase 2: Authentication** — JWT login flow with refresh tokens
+
+`/gywd:plan-phase 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/gywd:discuss-phase 2` — gather context first
+- `/gywd:research-phase 2` — investigate unknowns
+- Review roadmap
+
+---
+```
+
+### Phase Complete, Ready for Next
+
+Show completion status before next action:
+
+```
+---
+
+## ✓ Phase 2 Complete
+
+3/3 plans executed
+
+## ▶ Next Up
+
+**Phase 3: Core Features** — User dashboard, settings, and data export
+
+`/gywd:plan-phase 3`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/gywd:discuss-phase 3` — gather context first
+- `/gywd:research-phase 3` — investigate unknowns
+- Review what Phase 2 built
+
+---
+```
+
+### Multiple Equal Options
+
+When there's no clear primary action:
+
+```
+---
+
+## ▶ Next Up
+
+**Phase 3: Core Features** — User dashboard, settings, and data export
+
+**To plan directly:** `/gywd:plan-phase 3`
+
+**To discuss context first:** `/gywd:discuss-phase 3`
+
+**To research unknowns:** `/gywd:research-phase 3`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+
+### Milestone Complete
+
+```
+---
+
+## 🎉 Milestone v1.0 Complete
+
+All 4 phases shipped
+
+## ▶ Next Up
+
+**Plan v1.1** — Enhanced features and optimizations
+
+`/gywd:discuss-milestone`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/gywd:new-milestone` — create directly if scope is clear
+- Review accomplishments before moving on
+
+---
+```
+
+## Pulling Context
+
+### For phases (from ROADMAP.md):
+
+```markdown
+### Phase 2: Authentication
+**Goal**: JWT login flow with refresh tokens
+```
+
+Extract: `**Phase 2: Authentication** — JWT login flow with refresh tokens`
+
+### For plans (from ROADMAP.md):
+
+```markdown
+Plans:
+- [ ] 02-03: Add refresh token rotation
+```
+
+Or from PLAN.md `<objective>`:
+
+```xml
+<objective>
+Add refresh token rotation with sliding expiry window.
+
+Purpose: Extend session lifetime without compromising security.
+</objective>
+```
+
+Extract: `**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry`
+
+## Anti-Patterns
+
+### Don't: Command-only (no context)
+
+```
+## To Continue
+
+Run `/clear`, then paste:
+/gywd:execute-plan .planning/phases/02-auth/02-03-PLAN.md
+```
+
+User has no idea what 02-03 is about.
+
+### Don't: Missing /clear explanation
+
+```
+`/gywd:plan-phase 3`
+
+Run /clear first.
+```
+
+Doesn't explain why. User might skip it.
+
+### Don't: "Other options" language
+
+```
+Other options:
+- Review roadmap
+```
+
+Sounds like an afterthought. Use "Also available:" instead.
+
+### Don't: Fenced code blocks for commands
+
+```
+```
+/gywd:plan-phase 3
+```
+```
+
+Fenced blocks inside templates create nesting ambiguity. Use inline backticks instead.