@withmata/blueprints 0.3.2 → 0.3.4

package/.claude/skills/new-blueprint/SKILL.md

@@ -1,270 +0,0 @@
----
-name: new-blueprint
-description: Add a new blueprint to the withmata blueprints repository
----
-
-# Add a New Blueprint
-
-Guide the user through adding a new blueprint to this repo. This command ensures every blueprint follows the established conventions and is fully wired up.
-
-## Step 1: Understand the Conventions
-
-Read these files to understand the system you're adding to:
-
-```
-ENGINEERING.md                # Engineering preferences
-README.md                    # System overview and blueprint anatomy
-CHANGELOG.md                 # To update when done
-```
-
-Also scan existing complete blueprints to understand the quality bar:
-
-```
-blueprints/features/auth-better-auth/BLUEPRINT.md    # Best example of a feature blueprint
-blueprints/foundation/monorepo-turbo/BLUEPRINT.md    # Best example of a foundation blueprint
-blueprints/discovery/product-discovery/BLUEPRINT.md  # Best example of a discovery blueprint
-```
-
-## Step 2: Gather Information
-
-Ask the user:
-
-1. **"What pattern are you extracting?"** — What does it do? (e.g., "shared database layer with Drizzle", "Stripe billing integration", "email service with Resend")
-
-2. **"Which tier?"** — Discovery (produces docs), Foundation (project skeleton), or Feature (plugs into existing project)? Most new blueprints are Features.
-
-3. **"Is there an existing project to extract from?"** — If yes, get the path. If no, we're building from scratch — which is fine but harder.
-
-4. **"What should it be called?"** — Suggest a name following the convention: `{domain}-{tool}` for features (e.g., `auth-better-auth`, `db-drizzle-postgres`, `billing-stripe`, `email-resend`). Foundation and discovery blueprints use `{purpose}-{tool}` (e.g., `monorepo-turbo`, `product-discovery`).
-
-## Step 3: Extract or Build
-
-### If extracting from an existing project:
-
-Read the relevant code in the source project. Understand:
-- What files are involved
-- How they connect to each other
-- What's project-specific vs what's the reusable pattern
-- What dependencies are needed
-- What environment variables are required
-- How it integrates with the monorepo (workspace deps, turbo tasks, root scripts)
-
-Then create the blueprint:
-
-1. Create the directory: `blueprints/{tier}/{name}/`
-2. Create `files/` with the extracted code — generalize project-specific values:
-   - Replace npm scopes with `{{SCOPE}}`
-   - Replace app names with `{{APP_NAME}}`
-   - Replace project-specific emails, URLs, etc. with `{{PLACEHOLDER}}` and `// CONFIGURE:` comments
-   - Remove any business logic that's not part of the pattern
-3. Create `BLUEPRINT.md` following the structure below
-
-### If building from scratch:
-
-1. Create the directory: `blueprints/{tier}/{name}/`
-2. Build the code files in `files/`, following the conventions in ENGINEERING.md
-3. Create `BLUEPRINT.md` following the structure below
-
-## Step 4: Write the BLUEPRINT.md
-
-This is the most important file. It's what makes AI-assisted scaffolding intelligent rather than mechanical. Follow this structure:
-
-### Required sections (all tiers):
-
-```markdown
-# [Name] Blueprint — [Short Description]
-
-## Tier
-[Discovery | Foundation | Feature]
-
-## Status
-[Complete | In Progress | Planned]
-
-## Problem
-[What problem does this blueprint solve? Be specific about the pain point.]
-```
-
-### Additional sections for Feature blueprints:
-
-```markdown
-## Blueprint Dependencies
-
-[Does this blueprint require or recommend other blueprints be installed first?
-List them in a table with columns: Blueprint, Type (required/recommended), Why.
-If required, include a subsection explaining fallback behavior if the dependency is absent.
-If no dependencies, write "None."]
-
-## Single-Repo Adaptation
-
-[How does file placement, imports, and scripts differ for standalone (non-monorepo) apps?
-Include a path mapping table (monorepo vs single-repo) and a single-repo scripts example.
-Document what core patterns stay the same regardless of project type.]
-
-## Architecture
-
-### Core Pattern
-[How does this work at a high level?]
-
-### Key Decisions
-[For each major decision, document WHAT you chose and WHY. This is what lets the AI coding tool adapt intelligently.]
-
-- **[Decision 1]** (recommended/required) — [Explanation of what and why. Include alternatives if relevant.]
-- **[Decision 2]** (optional) — [Explanation]
-
-## Hard Requirements vs Recommended Defaults
-
-**Hard requirements:**
-- [Things that can't change]
-
-**Recommended defaults — ask during scaffolding:**
-
-| Choice | Recommended | Alternatives |
-|---|---|---|
-| [Choice 1] | [Default] | [Options] |
-
-## Dependencies
-
-### npm packages
-
-**Server:**
-| Package | Version | Purpose |
-|---|---|---|
-| [pkg] | [version] | [why] |
-
-**Client:**
-| Package | Version | Purpose |
-|---|---|---|
-
-### Environment Variables
-
-| Variable | Where | Description |
-|---|---|---|
-| [VAR] | [Server/Client] | [What it's for] |
-
-## Monorepo Wiring
-
-[How does this integrate across workspaces? Package exports, workspace deps, turbo tasks, root scripts. This section is critical — it's the hardest part to figure out from scratch.]
-
-## File Manifest
-
-| File | Purpose | Target Location |
-|---|---|---|
-| [file path in files/] | [what it does] | [where it goes in target project] |
-
-## Integration Steps
-
-[Ordered phases for scaffolding. Group related steps.]
-
-### Phase 1: [Name]
-1. [Step]
-2. [Step]
-
-### Phase 2: [Name]
-...
-
-## Maintenance Hooks
-
-[What needs to happen after changes to keep this working?]
-
-### Condensed Rules for project rules file
-
-```markdown
-### [name] maintenance
-- [rule 1]
-- [rule 2]
-```
-
-## References
-
-- [Links to docs, repos, etc.]
-```
-
-### Additional sections for Discovery blueprints:
-
-```markdown
-## Output
-[What documents are generated and where]
-
-## Process
-[The conversational flow — phases, frameworks, quality gates]
-```
-
-### Additional sections for Foundation blueprints:
-
-```markdown
-## Output
-[What project structure is generated — show the directory tree]
-
-## Architecture
-[Key structural decisions: why this tool, why this config, why this convention]
-
-## Expects from Discovery
-[What info it reads from the discovery context, if anything]
-```
-
-### Quality checklist for BLUEPRINT.md:
-
-Before considering the BLUEPRINT.md done, verify:
-
-- [ ] Every architectural decision explains WHY, not just WHAT
-- [ ] Configurable vs opinionated choices are clearly separated
-- [ ] Blueprint Dependencies section is present (even if "None")
-- [ ] Single-Repo Adaptation section documents path mapping and script differences
-- [ ] File manifest covers every file in files/ with both monorepo and single-repo target locations
-- [ ] Integration steps are ordered and phased, with conditional monorepo/single-repo phases
-- [ ] Dependencies list specific versions
-- [ ] Environment variables are documented with descriptions
-- [ ] Monorepo wiring is documented (this is always the hardest part)
-- [ ] Maintenance hooks define trigger-action pairs
-- [ ] Code files use `{{SCOPE}}`, `{{APP_NAME}}`, and `// CONFIGURE:` markers
-- [ ] References link to official docs
-
-## Step 5: Create the Scaffold Skill
-
-Create the skill as `.claude/skills/scaffold-{name}/SKILL.md`. Follow the pattern from existing skills (read `.claude/skills/scaffold-auth/SKILL.md` as the model). Add YAML frontmatter with `name` and `description` fields.
-
-Every scaffold skill must:
-
-1. **Read the blueprint** — BLUEPRINT.md and all files
-2. **Read project context** — `.project-context.md` for existing state
-3. **Explore the target project** — understand current structure
-4. **Ask clarifying questions** — based on the blueprint's configurable options
-5. **Adapt and scaffold** — replace placeholders, adapt to project structure
-6. **Update project context** — append to `.project-context.md`
-7. **Create maintenance skill** — as the final step, create a project-level maintenance skill at `<project>/.claude/skills/{name}-maintenance/SKILL.md` with `user-invocable: false` containing the blueprint's maintenance hooks
-8. **Summarize** — packages to install, env vars to set, manual steps remaining
-
-The skill should reference the BLUEPRINT.md as the source of truth for methodology and not duplicate its content.
-
-## Step 6: Update the Repo
-
-After the blueprint and skill are created:
-
-1. **Update README.md** — Add the new blueprint to the appropriate table (Complete or Planned) in the "Available blueprints" section. Add a scaffold command entry to the "Available commands" table.
-
-2. **Update CHANGELOG.md** — Add an entry under [Unreleased] → Added describing the new blueprint.
-
-3. **Update the directory structure** in README.md if it's shown there.
-
-4. **Check for a planned blueprint placeholder** — If `blueprints/features/{name}/BLUEPRINT.md` already existed as a planned placeholder, replace it entirely with the full BLUEPRINT.md. Don't try to preserve the placeholder content.
-
-5. **Ensure the new scaffold skill exists at `.claude/skills/scaffold-{name}/SKILL.md`.**
-
-## Step 7: Verify
-
-Before considering the blueprint done:
-
-1. Read back the BLUEPRINT.md and verify it meets the quality checklist from Step 4
-2. Read the scaffold skill and verify it follows the pattern from Step 5
-3. Verify all files in files/ use proper placeholders (no hardcoded scopes or app names)
-4. Verify README.md and CHANGELOG.md are updated
-5. Show the user a summary of everything that was created
-
-## Tips for Good Blueprints
-
-- **Extract from real projects** — Blueprints that come from battle-tested code are always better than theoretical ones.
-- **Document the WHY** — The code is the easy part. The decisions and reasoning are what make AI-assisted scaffolding intelligent.
-- **Keep it focused** — One blueprint, one problem. If you're tempted to add "and also X", that's probably a separate blueprint.
-- **Include the monorepo wiring** — Package exports, workspace dependencies, turbo tasks, root scripts. This is always the part people get wrong, and it's where the blueprint adds the most value.
-- **Think about maintenance** — What breaks silently if you forget to run something? Those are your maintenance hooks.
-- **Use existing blueprints as your quality bar** — Read auth-better-auth before writing yours. Match that level of detail.