devflow-kit 1.8.2 → 2.0.0

package/src/assets/skills/gap-analysis/references/check-layers.md

@@ -0,0 +1,125 @@
+# Gap Analysis Check Layers
+
+Detailed detection checklists and examples for each focus area. Use these patterns to systematically scan design artifacts.
+
+---
+
+## Completeness Checklist
+
+For each requirement or user story, verify:
+
+- [ ] **Testable success condition** — Can you write a test that definitively passes or fails?
+  - BAD: "Login should be fast"
+  - GOOD: "Login completes in < 2s at p99 under 100 concurrent users"
+
+- [ ] **Failure path specified** — What happens when the operation fails?
+  - BAD: "User submits order"
+  - GOOD: "User submits order → if payment fails, show error X and preserve cart; if DB fails, show error Y and queue retry"
+
+- [ ] **All actors identified** — Who initiates, who receives, who observes?
+  - BAD: "Email sent on registration"
+  - GOOD: "System sends welcome email to registered user; admin receives copy if domain is corporate"
+
+- [ ] **Data constraints defined** — Type, size, format, required/optional?
+  - BAD: "User provides profile photo"
+  - GOOD: "Profile photo: JPEG/PNG, max 5MB, min 100×100px, max 4096×4096px"
+
+- [ ] **Boundary conditions covered** — Empty state, single item, max capacity?
+  - BAD: "Show list of items"
+  - GOOD: "Show list (empty state: 'No items yet' message; max 1000 shown; pagination at 25)"
+
+---
+
+## Architecture Checklist
+
+For each new component or modification, verify:
+
+- [ ] **Integration contract defined** — How does this connect to existing systems?
+  - BAD: "Feature uses the existing auth service"
+  - GOOD: "Feature calls `/api/auth/verify` with Bearer token, expects `{userId, roles}` response"
+
+- [ ] **Layer ownership clear** — Which layer owns each responsibility?
+  - BAD: "Validate email format in the UI and save to DB"
+  - GOOD: "UI: format validation only; API: business rule validation; DB: constraint enforcement"
+
+- [ ] **Schema changes documented** — New tables, columns, indexes, migrations?
+  - BAD: "Store user preferences"
+  - GOOD: "Add `user_preferences` JSONB column to `users` table; migration #042; index on `user_id`"
+
+- [ ] **State management specified** — Where does state live, how does it change?
+  - BAD: "Track order status"
+  - GOOD: "Order status: `pending → confirmed → shipped → delivered | cancelled`; state machine in `OrderService`; event sourced"
+
+---
+
+## Security Checklist
+
+For each data flow across a trust boundary, verify:
+
+- [ ] **Authentication specified** — Who must be authenticated?
+  - BAD: "API endpoint to get user data"
+  - GOOD: "GET /api/users/:id — requires valid JWT; 401 if missing; 403 if requesting other user's data (RBAC: admin can access all)"
+
+- [ ] **Authorization specified** — Who can perform this action?
+  - BAD: "Admin can delete users"
+  - GOOD: "DELETE /api/users/:id — requires role=admin; cannot delete self; audit log entry required; soft delete only"
+
+- [ ] **Input validation specified** — What inputs are sanitized and how?
+  - BAD: "Accept search query from user"
+  - GOOD: "Search query: max 256 chars; strip HTML; parameterized query (no interpolation); rate limit 10 req/min"
+
+- [ ] **Secret handling specified** — How are credentials stored and transmitted?
+  - BAD: "Store API key for third-party service"
+  - GOOD: "API key stored in environment variable `THIRD_PARTY_KEY`; never logged; never returned in API responses; rotated quarterly"
+
+---
+
+## Performance Checklist
+
+For each data access or computation, verify:
+
+- [ ] **Query patterns identified** — Are queries bounded and indexed?
+  - BAD: "Get all orders for dashboard"
+  - GOOD: "GET /api/dashboard: fetch last 30 days orders for current user; index on `(user_id, created_at)`; max 500 rows; cached 5 min"
+
+- [ ] **Batch vs. loop specified** — Are N items fetched in 1 query or N queries?
+  - BAD: "Display user name next to each comment"
+  - GOOD: "Fetch all comments first, collect unique user IDs, batch-fetch users in single query: `SELECT * FROM users WHERE id = ANY($1)`"
+
+- [ ] **Async vs. sync specified** — Are slow operations handled asynchronously?
+  - BAD: "Send confirmation email after order"
+  - GOOD: "Email queued to background job (max 30s delay acceptable); order creation returns immediately; email failure does not fail order"
+
+- [ ] **Cache strategy specified** — What is cached, for how long, invalidated how?
+  - BAD: "Product catalog loaded on each request"
+  - GOOD: "Product catalog: Redis cache, 10-min TTL, invalidated on admin product update event; stale-while-revalidate pattern"
+
+---
+
+## Consistency Checklist (multi-issue)
+
+Across all issues in the batch, verify:
+
+- [ ] **Same entity, same name** — Is the same concept called the same thing?
+  - CONFLICT: Issue A calls it "customer", Issue B calls it "user", Issue C calls it "account"
+
+- [ ] **Compatible interfaces** — Does Issue A's output match Issue B's expected input?
+  - CONFLICT: Issue A returns `{ userId: string }`, Issue B expects `{ user_id: number }`
+
+- [ ] **Non-conflicting scope** — Does one issue's "in scope" conflict with another's "out of scope"?
+  - CONFLICT: Issue A scope includes "email notifications"; Issue B explicitly excludes "email"
+
+---
+
+## Dependencies Checklist (multi-issue)
+
+Across all issues in the batch, verify:
+
+- [ ] **Implementation order feasible** — Can issues be implemented independently?
+  - BLOCKED: Issue B creates a feature that stores data in a table Issue A creates — Issue A must ship first
+
+- [ ] **Shared files identified** — Do multiple issues modify the same files?
+  - RISK: Issues A, B, and C all modify `src/models/user.ts` — coordinate to avoid merge conflicts
+
+- [ ] **API contracts stable** — Do any issues change APIs that other issues consume?
+  - RISK: Issue A changes the auth token format; Issues B and C assume the old format — need coordinated rollout

package/src/assets/skills/git/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: git
+description: This skill should be used when the user asks to "commit changes", "create a pull request", "rebase safely", "manage branches", "fix merge conflicts", "undo a commit", "comment on a PR", "create a release", or performs any git/GitHub operations. Provides safety patterns, atomic commit formatting, PR descriptions, sensitive file detection, and GitHub API usage.
+user-invocable: false
+allowed-tools: Bash, Read, Grep, Glob
+---
+
+# Git & GitHub Patterns
+
+Unified skill for safe git operations, atomic commits, honest PR descriptions, and GitHub API interactions. Used by the Code agent and Git agent.
+
+## Iron Law
+
+> **EVERY COMMIT TELLS AN HONEST, ATOMIC STORY** [1][3]
+>
+> Each commit captures one logical change with a message that explains *what* changed
+> and *why*, not just *how*. Atomic commits make history reviewable, bisectable, and
+> revertable. Never bundle unrelated changes. Never write vague messages.
+
+---
+
+## When This Skill Activates
+
+- Staging files, creating commits, pushing branches
+- Creating or updating pull requests
+- Rebasing, force-pushing, merge conflicts, undoing commits
+- GitHub API operations (PR comments, issues, releases)
+- Any `git` or `gh` CLI command
+
+---
+
+## Safety
+
+### Lock File Handling
+
+Check for lock before git operations. If `.git/index.lock` exists, wait or abort.
+
+```bash
+[ -f .git/index.lock ] && echo "Lock exists - wait" && exit 1
+```
+
+### Sequential Operations
+
+```bash
+# WRONG: git add . & git status &
+# CORRECT:
+git add . && git status && echo "Done"
+```
+
+### Forbidden Operations
+
+| Action | Risk |
+|--------|------|
+| `git push --force` to main/master | Destroys shared history |
+| `git commit --no-verify` | Bypasses safety hooks |
+| `git reset --hard` without backup | Loses work permanently |
+| Parallel git commands | Causes lock conflicts |
+| Commit secrets/keys | Security breach |
+| Amend pushed commits | Requires force push |
+| Interactive rebase (`-i`) | Requires user input |
+
+### Amend Safety
+
+Only use `--amend` when ALL conditions are met:
+1. User explicitly requested amend, OR commit succeeded but hook auto-modified files
+2. HEAD commit was created by you in this conversation
+3. Commit has NOT been pushed to remote
+
+**Never amend**: If commit failed/rejected by hook, if pushed, or if unsure.
+
+### Branch Safety
+
+Never force push to: `main`, `master`, `develop`, `integration`, `trunk`, `release/*`, `staging`, `production`
+
+**Branch naming**: `feat/`, `fix/`, `release/`, `hotfix/` prefixes with short descriptions.
+
+### Quick Recovery
+
+```bash
+git reset --soft HEAD~1  # Undo commit, keep staged
+git reset HEAD~1         # Undo commit, keep unstaged
+```
+
+See `references/patterns.md` for extended recovery and stash workflows.
+
+---
+
+## Commits
+
+> **ATOMIC COMMITS WITH HONEST DESCRIPTIONS** — single logical change per commit, accurate messages.
+
+### Message Format
+
+```
+<type>(<scope>): <short summary> (max 50 chars)
+
+<optional body explaining what and why>
+
+<optional footer with references>
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+### Types
+
+| Type | Use When |
+|------|----------|
+| `feat` | New feature or capability |
+| `fix` | Bug fix |
+| `docs` | Documentation only changes |
+| `style` | Code style/formatting (no logic change) |
+| `refactor` | Code change that neither fixes nor adds |
+| `test` | Adding or updating tests |
+| `chore` | Build, dependencies, tooling |
+| `perf` | Performance improvements |
+
+### HEREDOC Format (Required)
+
+```bash
+git commit -m "$(cat <<'EOF'
+feat(auth): add JWT token validation
+
+Implement token validation middleware with:
+- Signature verification
+- Expiration checking
+
+Closes #123
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)"
+```
+
+### Atomic Grouping
+
+1. **By Feature/Module**: Changes within same directory or module
+2. **By Type**: Source code, tests, docs, config separately
+3. **By Relationship**: Files that change together for single logical purpose
+
+---
+
+## Pull Requests
+
+### Title Format
+
+`<type>(<scope>): <description>` — under 72 characters, imperative mood.
+
+### Description Sections
+
+| Section | Purpose |
+|---------|---------|
+| Summary | 2-3 sentences: what and why |
+| Changes | Features, fixes, refactoring by category |
+| Breaking Changes | User action required (or "None") |
+| Testing | Coverage, manual steps, gaps |
+| Related Issues | Closes/relates to links |
+
+### Size Assessment
+
+| Size | Lines Changed | Action |
+|------|---------------|--------|
+| Small | < 200 | Proceed normally |
+| Medium | 200-500 | Consider splitting if unrelated |
+| Large | 500-1000 | Recommend splitting |
+| Very Large | > 1000 | **WARN**: Split into smaller PRs |
+
+---
+
+## Sensitive File Detection
+
+### Never Commit These Patterns
+
+| Category | Patterns |
+|----------|----------|
+| Secrets | `.env`, `.env.*`, `*secret*`, `*password*`, `*credential*` |
+| Keys | `*.key`, `*.pem`, `*.p12`, `id_rsa*`, `id_ed25519*` |
+| Cloud | `.aws/credentials`, `.npmrc`, `.pypirc`, `.netrc` |
+| Temp | `*.tmp`, `*.log`, `*.swp`, `.DS_Store`, `*~` |
+
+### Quick Content Check
+
+Block commits containing:
+- `BEGIN.*PRIVATE KEY` — Private key material
+- `AKIA[0-9A-Z]{16}` — AWS access key
+- `gh[pousr]_[A-Za-z0-9_]{36,}` — GitHub token
+- Database URIs with credentials: `postgres://user:pass@`
+
+See `references/detection.md` for full `check_for_secrets()` function.
+
+---
+
+## GitHub API
+
+> **RESPECT RATE LIMITS OR FAIL GRACEFULLY** — remaining < 10 wait 60s, 1-2s between calls, batch where possible.
+
+### Standard Throttling
+
+```bash
+REMAINING=$(gh api rate_limit --jq '.resources.core.remaining')
+if [ "$REMAINING" -lt 10 ]; then sleep 60; fi
+sleep 1  # Between each API call
+```
+
+### PR Comments
+
+- Only lines in the PR diff can receive inline comments
+- Deduplicate before posting (same file + line = keep one)
+- Always include suggested fix and Claude Code attribution footer
+
+### Releases
+
+```bash
+[[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || exit 1  # Validate semver
+git tag -a "v${VERSION}" -m "Version ${VERSION}" && git push origin "v${VERSION}"
+gh release create "v${VERSION}" --title "v${VERSION}" --notes "$NOTES"
+```
+
+See `references/github-api.md` for extended API, CLI, and GraphQL patterns.
+
+---
+
+## Anti-Patterns
+
+| Violation | Impact | Fix |
+|-----------|--------|-----|
+| Parallel git commands | Index corruption | Sequential `&&` chains |
+| Grab-bag commits | Impossible to revert | One logical change per commit |
+| Blind staging (`git add .`) | Accidental secret commits | Stage specific files |
+| Force push to main | Destroys shared history | Create new commits |
+| Ignoring rate limits | API lockout | Check remaining, throttle |
+| Vague PR descriptions | Lost review context | Use structured template |
+| Hidden breaking changes | Consumer surprises | Mandatory section |
+
+---
+
+## Traceability Issue Template (D3)
+
+When creating or enriching a GitHub issue via the `ensure-traceable-issue` operation, use the following canonical D3 template:
+
+```markdown
+## Initial Request
+{The verbatim or paraphrased user request / scope statement that drove this task}
+
+## Product Requirements
+{Discovered requirements summary — user needs, acceptance criteria, constraints}
+
+## Implementation Plan
+[Design artifact posted as a collapsed comment — see linked comment below]
+```
+
+**Rules:**
+- Pre-existing issues: post a structured comment using D3 sections — NEVER rewrite the issue body.
+- New issues: create with D3 body; then post the design artifact as a `<details>` collapsed comment; link that comment URL in the `## Implementation Plan` section.
+- Issue creation is gated by the `COMPLIANCE` input: `enabled` → mandatory (DEGRADED states exempt), absent or `(none)` → optional.
+
+## Naming Conventions Authority
+
+When `.devflow/conventions.md` is present, it is the authoritative source for:
+- Branch Naming — prefix style (`feat/`, `fix/`, etc.), separator style, slug rules
+- PR Titles — conventional commit format, scope rules
+- Version PR Titles and Version Names (when applicable)
+
+The `learn-conventions` operation writes `.devflow/conventions.md` with a bounded scan (≤50 branches, ≤20 tags, ≤30 PR titles). To re-learn conventions from scratch, delete `.devflow/conventions.md` and re-run `learn-conventions`.
+
+When `.devflow/conventions.md` is absent, fall back to heuristic branch-prefix detection from existing remote branches.
+
+---
+
+## Extended References
+
+| Reference | Contents |
+|-----------|----------|
+| `references/sources.md` | Bibliography and citations |
+| `references/patterns.md` | Safety flows, commit patterns, PR templates |
+| `references/violations.md` | Safety, commit, and PR anti-patterns |
+| `references/detection.md` | Sensitive file regex patterns and check functions |
+| `references/github-api.md` | Rate limiting, CLI commands, GraphQL, releases, review thread GraphQL |
+
+## Checklist
+
+- [ ] All git commands sequential (`&&` chains)
+- [ ] No lock file conflicts
+- [ ] No sensitive files staged
+- [ ] Commit is atomic (single logical change)
+- [ ] Message follows conventional format with HEREDOC
+- [ ] PR description includes all required sections
+- [ ] Rate limits checked before batch API operations