mindforge-cc 10.0.3 → 11.0.0

package/.mindforge/skills/code-generation-patterns/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: code-generation-patterns
+version: 1.0.0
+min_mindforge_version: 0.3.0
+status: stable
+triggers: code generation, template engine, AST manipulation, scaffolding pattern, code mod, source transform, code generator, boilerplate generation, schema-to-code, type generation, code synthesis, metaprogramming
+---
+
+# Skill — Code Generation Patterns
+
+## When this skill activates
+Any task involving automated code generation, scaffolding, code mods, template
+engines, AST transformations, or schema-to-code pipelines.
+
+## Mandatory actions when this skill is active
+
+### Before generating code
+1. Determine the generation approach based on the use case.
+2. Validate that generation is worthwhile (see "When NOT to generate" below).
+3. Ensure generated output is clearly marked with a header comment.
+
+### Approaches
+
+**Template-based (Handlebars/EJS):**
+- Best for: simple, repetitive file generation with known structure.
+- Use when: the output varies only in names/values, not in structure.
+- Tools: Handlebars, EJS, Mustache, Liquid.
+- Pattern: define template → inject variables → write output file.
+
+**AST-based (babel/ts-morph):**
+- Best for: code transforms, refactors, and modifications to existing code.
+- Use when: you need to understand code structure, not just text patterns.
+- Tools: babel (JavaScript), ts-morph (TypeScript), jscodeshift (codemods).
+- Pattern: parse source → traverse AST → apply transforms → print modified source.
+
+**Schema-based (OpenAPI/GraphQL/JSON Schema):**
+- Best for: generating clients, types, validators from a single source of truth.
+- Use when: a schema already defines the contract and code must conform.
+- Tools: openapi-generator, graphql-codegen, json-schema-to-typescript.
+- Pattern: schema file → generator config → output typed client/types.
+
+### Scaffolding
+
+**Project generators:**
+- Yeoman, create-* CLIs, degit for template repos.
+- Include: directory structure, config files, CI setup, README template.
+- Version your generator — breaking changes need migration paths.
+
+**File generators:**
+- Plop, Hygen for generating individual files within a project.
+- Pattern: define prompts → apply template → write to correct directory.
+- Keep templates co-located with the generator config.
+
+### Code mods
+
+**jscodeshift (JavaScript/TypeScript bulk refactors):**
+- Write transform as a function: `(file, api) => api.jscodeshift(file.source)...`
+- Test on a single file first, then run across codebase.
+- Always commit before running a codemod (easy revert).
+
+**ts-morph (TypeScript-aware transforms):**
+- Full TypeScript compiler API access.
+- Can add/remove/rename imports, functions, classes, types.
+- Pattern: create Project → get SourceFiles → manipulate → save.
+
+**Systematic process:**
+1. Find all instances of the pattern to transform.
+2. Write the transform function.
+3. Dry-run with diff output.
+4. Apply and verify tests still pass.
+
+### When NOT to generate
+
+- If it is simpler to write by hand (fewer than 3 instances).
+- If generated code needs frequent manual edits (generator is wrong).
+- If the template is harder to understand than the output.
+- If the schema changes so frequently that regeneration becomes a bottleneck.
+- If the team cannot maintain the generator long-term.
+
+### Quality standards for generated code
+
+- Generated files MUST have a header: `// THIS FILE IS AUTO-GENERATED. DO NOT EDIT.`
+- Generated code must pass the same lint/format rules as hand-written code.
+- Generator must be idempotent (running twice produces same output).
+- Include a `regenerate` script in package.json for easy re-generation.
+- Test the generator itself, not just the generated output.
+
+## Self-check before task completion
+- [ ] Did I follow the mandatory actions for this skill?
+- [ ] Did I apply the patterns appropriate to the context?
+- [ ] Did I verify the implementation meets the criteria above?
+- [ ] Did I document decisions and trade-offs made?

package/.mindforge/skills/code-review-methodology/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: code-review-methodology
+version: 1.0.0
+min_mindforge_version: 0.1.0
+status: stable
+triggers: code review methodology, review framework design, review checklist creation, PR review strategy, what to review guide, review comment style, LGTM criteria definition, PR sizing guideline, review feedback technique, constructive review approach, review priority matrix, review depth strategy
+---
+
+# Skill — Code Review Methodology
+
+## When this skill activates
+Any task involving establishing code review practices, creating review checklists,
+defining PR standards, improving review feedback quality, or performing a structured review.
+
+## Mandatory actions when this skill is active
+
+### Before starting a review
+1. Check PR size — if >800 lines, request the author split it.
+2. Read the PR description to understand intent before reading code.
+3. Identify the review depth needed (critical path = deep, config = surface).
+
+### During review
+- Review in priority order: correctness → security → performance → readability → style.
+- Categorize every comment (blocking, suggestion, question, praise).
+- Ask "What about X?" not "You should X."
+- Limit blocking comments to actual blockers — save nitpicks for suggestions.
+
+### After review
+- Summarize overall assessment in the review summary.
+- State clearly: Approve, Request Changes, or Comment.
+- If Request Changes, list the specific blocking items.
+
+## Review priority matrix
+
+| Priority | Category | Examples |
+|----------|----------|----------|
+| 1 (Critical) | Correctness | Logic bugs, data loss, race conditions |
+| 2 (High) | Security | Auth bypass, injection, secret exposure |
+| 3 (Medium) | Performance | N+1 queries, missing indexes, memory leaks |
+| 4 (Low) | Readability | Unclear names, missing comments, complex nesting |
+| 5 (Minimal) | Style | Formatting, import order, bracket placement |
+
+Focus 80% of review effort on priorities 1-3. Style issues should be handled by linters, not humans.
+
+## PR sizing guidelines
+
+| Size | Lines Changed | Review Time | Quality |
+|------|--------------|-------------|---------|
+| XS | <50 | 5 min | Excellent |
+| S | 50-200 | 15 min | Good |
+| M | 200-400 | 30 min | Acceptable |
+| L | 400-800 | 60 min | Risky |
+| XL | >800 | ??? | Split it |
+
+Rules:
+- Ideal PR: <400 lines of meaningful changes (exclude generated code, lockfiles).
+- If a PR is large, split into: refactoring prep → core change → cleanup.
+- One logical change per PR. "While I was here" changes go in separate PRs.
+
+## Comment types
+
+### Blocking (must fix before merge)
+```
+[blocking] This SQL query is vulnerable to injection.
+Use parameterized queries: `db.query('SELECT * FROM users WHERE id = $1', [id])`
+```
+
+### Suggestion (consider, but not required)
+```
+[suggestion] Consider extracting this into a helper function —
+it appears three times across this file and `utils.ts`.
+```
+
+### Question (help me understand)
+```
+[question] What happens if `user` is null here?
+I don't see a null check upstream.
+```
+
+### Praise (reinforce good patterns)
+```
+[praise] Great use of the builder pattern here —
+much cleaner than the previous imperative approach.
+```
+
+## LGTM criteria
+
+A PR is ready to merge when ALL of these are true:
+- [ ] No blocking comments remain unresolved.
+- [ ] Tests exist for the change (unit + integration where appropriate).
+- [ ] CI pipeline passes (lint, type check, tests, build).
+- [ ] Documentation updated if public API or behavior changed.
+- [ ] No TODOs added without a linked issue/ticket.
+- [ ] PR title and description accurately describe the change.
+
+## Review depth by change type
+
+### Deep Review (read every line, trace data flow)
+- Auth/security code
+- Payment/billing logic
+- Data migrations
+- Public API changes
+- Core business logic
+
+### Standard Review (understand intent, spot issues)
+- New features
+- Bug fixes
+- Internal refactoring
+- Test additions
+
+### Surface Review (sanity check, trust CI)
+- Dependency updates (check changelog, breaking changes)
+- Config changes (verify values are correct)
+- Documentation updates (check accuracy)
+- Generated code (verify generator config, spot-check output)
+
+## Feedback style guide
+
+### Do
+- "What about handling the case where X is empty?"
+- "Nice pattern — this is cleaner than the previous approach."
+- "Could you add a comment explaining why this timeout is 30s?"
+- "I think there's an edge case: [describe scenario]"
+
+### Don't
+- "You should use X instead." (prescriptive without context)
+- "This is wrong." (unconstructive)
+- "Why didn't you just do X?" (implies incompetence)
+- "Nit: [style preference]" on every other line (use a linter)
+
+### Principles
+- Assume the author had a reason. Ask before suggesting alternatives.
+- Be specific: "line 42 could throw if `data` is null" not "error handling is missing."
+- Offer solutions with your criticism — show a better approach.
+- Praise patterns you want to see more of (positive reinforcement works).
+
+## Common things to check
+
+### Correctness
+- Off-by-one errors in loops and ranges.
+- Null/undefined handling on external data.
+- Race conditions in async code.
+- Error paths — what happens when things fail?
+
+### Security
+- User input flows to SQL/HTML/shell without sanitization?
+- Auth checks on every protected endpoint?
+- Secrets hardcoded or logged?
+- CORS/CSRF properly configured?
+
+### Performance
+- N+1 queries in loops?
+- Missing database indexes for query patterns?
+- Unbounded data fetches (no LIMIT)?
+- Expensive operations in hot paths?
+
+### Maintainability
+- Will the next developer understand this in 3 months?
+- Are there tests to catch regressions?
+- Is the abstraction level consistent?
+- Are error messages actionable?
+
+## Anti-patterns to avoid
+- Rubber-stamping (approving without reading — defeats the purpose).
+- Nitpick storms (10 style comments on a 20-line PR — use a linter).
+- Gatekeeping (blocking for subjective preferences, not objective issues).
+- Drive-by reviews (leaving one comment, never returning for follow-up).
+- "I would have done it differently" without identifying an actual problem.
+- Reviewing only the diff, not the context (the bug might be in surrounding code).
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] Reviewed in priority order (correctness → security → performance → readability)?
+- [ ] Every comment categorized (blocking/suggestion/question/praise)?
+- [ ] No nitpicks marked as blocking?
+- [ ] Summary provided with clear approve/request-changes verdict?
+- [ ] Feedback is specific, constructive, and offers solutions?
+- [ ] PR size is within guidelines (or split requested)?

package/.mindforge/skills/code-tour/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: code-tour
+version: 1.0.0
+min_mindforge_version: 10.0.6
+status: stable
+triggers: code tour, codebase walkthrough, interactive tour, reading path, annotated guide, code exploration guide, progressive tour, guided exploration, architecture tour, code narrative, file tour, source walkthrough
+---
+
+# Skill — Code Tour
+
+## When this skill activates
+
+When generating guided explorations of a codebase to help someone understand its
+architecture, data flow, or implementation patterns. Use when onboarding new team
+members, documenting complex subsystems, or creating learning paths through
+unfamiliar code.
+
+A code tour is NOT a README or API reference — it is a narrative journey through
+source files in a deliberate order, with annotations explaining the "why" at each
+stop, building understanding progressively.
+
+## Mandatory actions when this skill is active
+
+### Before generating the tour
+
+1. **Determine tour scope and audience:**
+   - Who is this tour for? (new hire, external contributor, senior dev in new area)
+   - What should they understand after completing the tour?
+   - What prior knowledge can be assumed?
+   - Scope: full system overview vs focused subsystem deep-dive
+
+2. **Map the dependency graph:**
+   - Identify the entry point(s) — `main`, `index`, `app`, CLI handler
+   - Trace first-level imports from the entry point
+   - Identify core modules vs utility/helper modules
+   - Note circular dependencies or surprising coupling
+
+3. **Select a tour strategy:**
+
+   | Strategy | Best for | Approach |
+   |----------|----------|----------|
+   | Entry-point-first | Full system overview | Start at main, trace outward |
+   | Data-flow | APIs, pipelines | Follow a request from ingress to response |
+   | Layer-by-layer | Layered architecture | Config → Entry → Core → Utils → Edge |
+   | Feature-slice | Specific feature | All files involved in one user story |
+   | Dependency-graph | Library/framework | Follow import tree breadth-first |
+
+4. **Plan the stop sequence:**
+   - 8-15 stops is ideal (fewer feels shallow, more causes fatigue)
+   - Each stop should build on the previous one
+   - Alternate between "big picture" and "zoom in" stops
+   - End with a synthesis stop that ties everything together
+
+### During tour generation
+
+**Stop format (mandatory for each stop):**
+
+```markdown
+## Stop N: [Descriptive Title]
+
+**File:** `src/path/to/file.ts` (lines 42-87)
+
+**Why this file matters:**
+[1-2 sentences on this file's role in the system]
+
+**What to notice:**
+- [Key pattern, design decision, or technique used here]
+- [Relationship to previous stop]
+- [Any non-obvious behavior or convention]
+
+**Key code:**
+```[language]
+// The critical section, with inline annotations
+function handleRequest(ctx: Context) {
+  // Notice: middleware chain is resolved here, not at registration time
+  const pipeline = ctx.middleware.resolve();
+  // ...
+}
+```
+
+**Checkpoint:** After this stop, you should understand:
+- [Concrete understanding goal 1]
+- [Concrete understanding goal 2]
+```
+
+**Progressive complexity rules:**
+- Stop 1-3: Configuration, entry points, "what runs when the app starts"
+- Stop 4-7: Core business logic, primary data flow, key abstractions
+- Stop 8-10: Edge cases, error handling, performance-critical paths
+- Stop 11+: Advanced patterns, extension points, testing infrastructure
+
+**Annotation principles:**
+- Explain WHY this code exists, not WHAT it does (the code shows what)
+- Highlight design decisions: "This uses X pattern because..."
+- Call out conventions: "All handlers in this project follow this shape..."
+- Note historical context if relevant: "This was refactored from X because..."
+- Flag potential confusion points: "This looks like X but is actually Y because..."
+
+**Connecting stops:**
+- Each stop after the first must reference how it relates to previous stops
+- Use phrases like: "Remember the middleware we saw in Stop 3? This is where..."
+- Draw the thread of data/control flow between stops explicitly
+- If stops are non-linear, explain why you're jumping to this location
+
+### After tour generation
+
+1. **Add a tour summary:**
+   ```markdown
+   ## Tour Summary
+
+   **Total stops:** N
+   **Estimated reading time:** ~X minutes
+   **Key takeaways:**
+   1. [Most important architectural insight]
+   2. [Critical pattern used throughout]
+   3. [Key design decision and its rationale]
+
+   **Suggested next tours:**
+   - [Related subsystem that builds on this understanding]
+   - [Deeper dive into one area touched here]
+   ```
+
+2. **Verify tour coherence:**
+   - Read through all stops sequentially — does the narrative flow?
+   - Does each checkpoint build on the previous one?
+   - Would the target audience actually understand this?
+   - Are file paths and line numbers accurate and current?
+
+3. **Output format:**
+   - Single markdown file: `TOUR-[name].md` in the project root or `docs/tours/`
+   - Include a table of contents with links to each stop
+   - If the tour references specific commits or versions, note the git ref
+
+## Self-check before task completion
+
+Before marking a code tour task done:
+
+- [ ] Did I identify the target audience and their prior knowledge level?
+- [ ] Did I select an appropriate tour strategy for the scope?
+- [ ] Does the tour have 8-15 stops with progressive complexity?
+- [ ] Does every stop include: file path, why it matters, what to notice, checkpoint?
+- [ ] Does the narrative flow logically from one stop to the next?
+- [ ] Are file paths and line references accurate to the current codebase?
+- [ ] Did I include a summary with key takeaways and suggested next tours?
+- [ ] Would the target audience actually learn what they need from this tour?

package/.mindforge/skills/codebase-onboarding/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: codebase-onboarding
+version: 1.0.0
+min_mindforge_version: 10.0.4
+status: stable
+triggers: onboarding, new repo, unfamiliar codebase, codebase summary, knowledge graph, entry points, learning path, repo overview, architecture discovery, codebase map, project familiarization, code exploration
+---
+
+# Skill — Codebase Onboarding
+
+## When this skill activates
+
+When entering a new or unfamiliar repository for the first time, when asked to
+summarize or map a codebase, or when needing to build a mental model before
+making changes. Also activates when explicitly asked to generate an onboarding
+report or learning path.
+
+## Mandatory actions when this skill is active
+
+Execute the following auto-summarization pipeline in order:
+
+### Step 1 — Detect Stack
+
+Identify the technology stack by examining:
+
+- **Language(s)**: file extensions, shebang lines, language-specific config files
+- **Framework(s)**: package.json dependencies, requirements.txt, go.mod, Cargo.toml
+- **Build system**: Makefile, webpack, vite, turbopack, gradle, cargo, mix
+- **Test framework**: jest, pytest, vitest, go test, RSpec, xUnit
+- **Package manager**: npm, yarn, pnpm, pip, poetry, cargo, go modules
+- **Infrastructure**: Docker, Kubernetes, Terraform, CDK, serverless configs
+
+### Step 2 — Find Entry Points
+
+Locate all entry points into the application:
+
+- Main files (main.ts, index.ts, app.py, main.go, Program.cs)
+- CLI entry points (bin/ directory, package.json bin field)
+- Route definitions (router files, controller registrations)
+- Event handlers (message consumers, cron jobs, webhook handlers)
+- Worker/queue processors
+- Migration entry points (seed files, migration runners)
+
+### Step 3 — Build Module Dependency Graph
+
+Create a graph where:
+
+- **Nodes** = modules, packages, or major source directories
+- **Edges** = imports, function calls, event emissions between modules
+- Identify circular dependencies (flag as architectural debt)
+- Note external service dependencies (databases, APIs, queues)
+
+### Step 4 — Identify Hot Paths
+
+Find the most critical files by measuring:
+
+- **Most imported**: files that appear in the most import statements
+- **Most modified**: files with the highest git commit frequency (last 90 days)
+- **Largest fan-out**: files that import the most other modules
+- **Gateway files**: files that bridge between major subsystems
+
+### Step 5 — Generate Learning Path
+
+Create an ordered reading list that builds understanding progressively:
+
+1. Configuration files (understand the shape of the project)
+2. Entry points (understand how the system starts)
+3. Core domain logic (understand what the system does)
+4. Infrastructure/adapters (understand how it connects to the world)
+5. Edge cases and error handling (understand failure modes)
+6. Tests (understand expected behavior and invariants)
+
+### Step 6 — Output Report
+
+Write `ONBOARDING-REPORT.md` to `.planning/` containing:
+
+- Stack summary (one-line per technology)
+- Entry points list (file path + purpose)
+- Dependency graph (ASCII or Mermaid format)
+- Hot paths table (file, import count, commit frequency)
+- Learning path (ordered reading list with file paths)
+- Key architectural decisions or patterns observed
+- Known debt or areas of concern
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] Did I identify the stack correctly (language, framework, build, test)?
+- [ ] Did I find ALL entry points (not just the obvious main file)?
+- [ ] Did I build a dependency graph showing module relationships?
+- [ ] Did I identify hot paths (most-imported and most-modified)?
+- [ ] Did I create a usable learning path (ordered, progressive)?
+- [ ] Did I output ONBOARDING-REPORT.md to .planning/?
+- [ ] Is the report useful to someone with zero prior context?