[#101] feat: sprint planning with skills (/refine-story, /plan-tasks, /write-issue)

[rucka]

Summary

What Changed

3 new Agent Skills for sprint planning (/refine-story, /plan-tasks, /write-issue), how-to thinning to orchestrators, KB distribution pipeline bug fixes, centralized @pair/markdownlint-config tooling, and markdown lint cleanup.

Why This Change

Sprint planning skills enable structured, idempotent workflows for story refinement and task breakdown — composing /write-issue for PM tool integration. How-to files become thin orchestrators that delegate procedural detail to skills, reducing duplication and improving maintainability. Markdownlint centralized config ensures consistent MD quality across all workspaces.

Story Context

User Story: As a product engineer planning sprint work with AI assistance, I want to invoke /refine-story and /plan-tasks which compose /write-issue for PM tool integration, with how-to-08 and how-to-09 thinned to orchestrators, so that story refinement and task breakdown follow a structured process that produces properly formatted issues in the adopted PM tool.

Acceptance Criteria: 11 ACs — all covered. See #101 for full Given-When-Then details.

Closes #101

Changes Made

Implementation Details

• T-1: /write-issue capability skill — PM tool abstraction, template-driven formatting, $id create/update, extensible type system, no tool fallback
• T-2: /refine-story process skill — section-level idempotent refinement (selection → requirements → technical → sprint readiness → documentation)
• T-3: /plan-tasks process skill — task-level idempotent breakdown (story analysis → task identification → definition → dependency graph → AC coverage)
• T-4: how-to-08 thinned from ~287→104 lines (orchestrator only)
• T-5: how-to-09 thinned from ~358→126 lines (orchestrator only)
• T-6: Template updates (user-story-template.md functional-first ordering, task-template.md Dependency Graph + AC Coverage)
• Bug fixes: skill ref rewrite in secondary (copy) targets, INIT_CWD override for pnpm --filter, skillNameMap propagation, link re-rooting
• Docs: target resolution docs (commands.md, cli-workflows.md, cli-contracts.md, README)
• Lint: MD040 bare fences + MD012 consecutive blanks across 28 files
• Tooling: Centralized @pair/markdownlint-config in tools/ (following eslint/prettier pattern), mdlint:fix wired into quality-gate, Custom Gate Registry updated in project adoption

Files Changed

• Added: .skills/process/refine-story/SKILL.md, .skills/process/plan-tasks/SKILL.md, .skills/capability/write-issue/SKILL.md
• Added: tools/markdownlint-config/ (package.json, .markdownlint.jsonc, .markdownlintignore, bin scripts)
• Modified (KB): how-to-08, how-to-09, how-to-10, how-to-11, user-story-template.md, task-template.md, AGENTS.md, 10 SKILL.md sources (MD040 fixes), 2 quality-assurance docs (MD012 fixes)
• Modified (CLI): cli.ts, dispatcher.ts, update/handler.ts, install/handler.ts, operations.ts + all test files
• Modified (docs): commands.md, cli-workflows.md, cli-contracts.md, README.md, eslint-config/README.md
• Modified (infra): scripts/smoke-tests/lib/utils.sh, turbo.json, pnpm-workspace.yaml, package.json
• Modified (adoption): .pair/adoption/tech/way-of-working.md (Custom Gate Registry)
• Generated: .claude/skills/ (10 files), AGENTS.md, CLAUDE.md, .pair/ (distributed copies)

Testing

Test Coverage

• Unit Tests: 299 tests passing (40 test files) — includes new handler tests for skill ref rewriting, secondary target distribution, INIT_CWD override
• Smoke Tests: 6/6 scenarios passing (pnpm smoke-tests) — fixed INIT_CWD leak from pnpm invocation
• Manual Testing: Skills invocable in Claude Code, idempotent re-invocation verified, graceful degradation cascade tested

Test Results

Test Suite: ✅ 40 files passing
Tests: ✅ 299 passed
Smoke Tests: ✅ 6/6 passing
Quality Gate: ✅ All gates passing (lint, ts:check, test, prettier, mdlint)

Testing Strategy

• Regression: Bug 4 (secondary target skill refs) + Bug 5 (config ordering) covered with dedicated tests in both install and update handlers
• Edge Cases: empty targets, missing files, flatten+prefix interaction, INIT_CWD propagation
• Idempotency: skills tested for re-invocation on partial state (partial refinement, partial tasks)

Quality Assurance

Code Quality Checklist

• Code follows established style guides and conventions
• Error handling implemented for edge cases
• No debugging code or console logs left behind
• ESLint complexity limit respected (extracted rewriteSkillRefsInTarget helper)
• Markdownlint zero errors across all workspaces

Documentation

• CLI target resolution documented (commands.md, cli-workflows.md)
• Monorepo usage section added (cli-workflows.md)
• cli-contracts.md updated with INIT_CWD precedence
• README.md updated with target description

Reviewer Guide

Review Focus Areas

1. Skill content: verify /refine-story, /plan-tasks, /write-issue SKILL.md files follow the check→skip→act→verify pattern and composition interface
2. How-to thinning: confirm how-to-08 and how-to-09 retained orchestration flow without duplicating skill content
3. Bug fixes: secondary target skill ref rewriting (update/handler.ts:260-305, install/handler.ts:206-249)
4. Template updates: user-story-template.md functional-first ordering, task-template.md Dependency Graph + AC Coverage format
5. Markdownlint config: tools/markdownlint-config/ pattern consistency with eslint/prettier, quality-gate integration

Testing the Changes

git checkout feature/#101-sprint-planning-skills
pnpm install
pnpm quality-gate        # lint, ts:check, test, prettier, mdlint
pnpm smoke-tests         # 6 smoke scenarios
pnpm --filter pair-cli dev update .  # regenerate distributed files

[rucka]

Code Review — PR #110

Reviewer: Claude (AI-assisted)
Date: 2026-02-12
Story: #101 — Sprint planning with skills
Review Type: Feature
Decision: TECH-DEBT (Approved — track debt separately)

---

Review Summary

3 new Agent Skills (/refine-story, /plan-tasks, /write-issue), 2 how-to files thinned to orchestrators, CLI bug fixes (skill ref rewriting, INIT_CWD, secondary targets), template updates, docs, and markdown lint cleanup. 56 files, +3239/-1898.

Business Value: Sprint planning workflow fully covered by skills. Completes Circle 1 (daily dev workflow).

---

Quality Gates: PASS

Gate	Status
Lint	PASS
ts:check	PASS
Tests	PASS (81 test suites, 299+ tests)
Prettier	PASS

---

Code Review Findings

Positive Feedback

• Excellent test coverage: 17+ regression tests for 4 bug fixes, each with dedicated suites in both install and update handlers
• Consistent skill design: All 3 new skills follow check→skip→act→verify pattern rigorously (25+ instances per skill)
• Clean composition interfaces: /write-issue properly documents composition by /refine-story and /plan-tasks
• Correct template paths: All skill references to templates verified against actual files
• Strong TypeScript typing: Discriminated unions, proper Map typing, no any in changed code
• How-to thinning well-executed: how-to-08 (287→104 lines), how-to-09 (358→126 lines) — both standalone readable

Minor Issues

1. Code duplication — applySkillRefsToNonSkillRegistries, rewriteSkillRefsInTarget, postCopyOps, resolveDatasetRoot duplicated between install/handler.ts and update/handler.ts (~150 lines). Recommend extracting to shared module.
2. Missing JSDoc — Internal handler helpers lack documentation (35% in install, 25% in update). Complex functions like rewriteSkillRefsInTarget would benefit from JSDoc.
3. Graceful degradation wording — /refine-story and /plan-tasks mark /write-issue as Required in composition table but describe graceful degradation in notes. Minor inconsistency, not blocking.

---

Definition of Done: 14/15

All criteria met except "Code reviewed and merged" (this review completes the review part).

---

Tech Debt: 9 items flagged

Severity	Count	Key Items
High	2	Handler code duplication (~150 lines identical)
Medium	2	Documentation gaps in handler modules
Low	5	Context type inconsistency, missing inline comments, sequential file processing

Recommendation: Track handler duplication as tech debt item for next refactoring pass.

---

Adoption Compliance: Level 4

No /verify-adoption or /assess-stack installed. No new dependencies added. No adoption changes needed.

---

Risk Assessment

Risk	Impact	Probability	Mitigation
Handler duplication diverges over time	Medium	Medium	Extract shared module in next story
Skill content evolves without tests	Low	Low	Manual validation sufficient for markdown skills

---

Verdict

APPROVED (TECH-DEBT) — No critical or major issues. All quality gates pass. All AC met. Minor duplication debt tracked for future resolution.

[rucka]

Tech Debt Resolution

All 9 items from the code review addressed in 26729ef:

HIGH (2) — Handler duplication eliminated

Item	Resolution
Handler code duplication (~150 lines identical)	4 functions extracted to domain modules: postCopyOps → #registry/operations, rewriteSkillRefsInTarget + applySkillRefsToNonSkillRegistries → #registry/skill-refs (new), resolveDatasetRoot → #config/kb-resolver
Handler duplication diverges over time	Shared module prevents drift — single source of truth

MEDIUM (2) — Documentation + type consistency

Item	Resolution
Documentation gaps in handler modules	JSDoc on all 4 extracted functions + SkillRefContext type + DatasetResolvableConfig/DatasetResolveOptions types
Context type inconsistency	UpdateContext (bloated) vs inline { fs, baseTarget, pushLog } → both now use SkillRefContext from #registry/skill-refs

LOW (5) — Minor items

Item	Resolution
Context type inconsistency (UpdateContext bloat)	SkillRefContext extracts only the 3 fields the function needs
Missing inline comment in install handler	Both handlers now share the same code path with consistent comments
Sequential file processing	Kept as-is — walkMarkdownFiles + sequential write is correct for filesystem ops (parallel writes risk corruption on same directory)
Skill content evolves without tests	17 new unit tests for extracted functions (8 skill-refs, 4 postCopyOps, 5 resolveDatasetRoot)
Handler duplication risk (future)	Architectural fix: shared functions in #registry and #config follow existing domain-module pattern

Stats

• ~93 duplicated lines eliminated
• 17 new unit tests (316 total, all green)
• Quality gate passes (lint, ts:check, test, prettier, mdlint)