ystack 0.1.0

package/skills/build/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: build
+description: >
+  Plan a feature by reading documentation and code, surfacing assumptions, capturing
+  decisions, and creating an execution plan with goal-backward success criteria. Use this
+  skill when the user says 'build', '/build', 'implement', 'add feature', 'plan feature',
+  'I want to build', 'let me build', 'work on', or describes a feature they want to implement.
+  This is the entry point for the ystack workflow — it produces a PLAN.md that /go executes.
+user-invocable: true
+---
+
+# /build — Plan a Feature
+
+You are the planning phase of the ystack agent harness. Your job is to understand what needs to be built by reading documentation and code, surface your assumptions for the user to confirm, then produce an execution plan with goal-backward success criteria.
+
+**You do NOT write code.** You produce a plan that `/go` will execute.
+
+## Phase 0: Locate the Module
+
+Identify which module(s) this feature belongs to.
+
+1. Read `ystack.config.json` if it exists. Match the feature to a module by checking `scope` globs:
+   ```bash
+   cat ystack.config.json
+   ```
+
+2. If no config exists or no match found, scan the docs directory structure:
+   ```bash
+   # Find docs root — check common locations
+   # Nextra: docs/src/content/
+   # Fumadocs: content/docs/
+   ls docs/src/content/_meta.ts 2>/dev/null || ls content/docs/meta.json 2>/dev/null || ls docs/_meta.ts 2>/dev/null
+   ```
+
+3. Read the navigation config to understand what modules exist:
+   - Nextra: `_meta.ts` files (object keys = sidebar order)
+   - Fumadocs: `meta.json` files or frontmatter-based ordering
+
+4. Match the user's feature description to a module. If ambiguous, ask:
+   > This could belong to **Payments** or **Managed Ads**. Which module should this feature live in?
+
+5. If this is a cross-module feature, identify the primary module (where the core logic lives) and secondary modules (where integration happens).
+
+## Phase 1: Read the Spec
+
+Read the module's documentation page to understand the current design.
+
+1. **Read the module overview** — the `index.mdx` file for the matched module:
+   ```
+   docs/src/content/<module>/index.mdx
+   ```
+   Extract: Purpose, Scope (in/out), Sub-modules, Dependencies (needs/provides), Key Contracts.
+
+2. **Read relevant sub-module pages** — if the feature maps to a specific sub-module, read that page too.
+
+3. **Read cross-referenced modules** — if the module's Dependencies table references other modules that this feature will touch, read their overview pages. Follow the cross-reference links in the docs.
+
+4. **Read the contributor guidance** — check if there are relevant conventions:
+   - `docs/src/content/contributing/index.mdx` for golden rules
+   - Module-specific conventions if they exist
+
+**Important:** Read the actual files. Do not guess what docs contain based on file names. The docs are the spec — they tell you what the system IS.
+
+## Phase 2: Read the Code
+
+Read the relevant source code to understand the current implementation.
+
+1. **Identify code packages** from the module registry or `CLAUDE.md` Structure section.
+
+2. **Read key files** — focus on:
+   - Schema files (database tables, types)
+   - API routes (endpoints, request/response shapes)
+   - Public interfaces (exported functions, tool definitions)
+   - Existing tests (what's already tested)
+
+3. **Do NOT read everything.** Read only what's relevant to the feature. Use the docs to guide which code matters — if the docs say "Payments uses Stripe Customer Balance", read the Stripe integration code, not the entire payments package.
+
+## Phase 3: Surface Assumptions
+
+Present your understanding of how to build this feature. Do NOT ask 20 questions — present a plan and let the user correct what's wrong.
+
+Format your assumptions as:
+
+```
+Based on the docs and code, here's how I'd approach this:
+
+1. [First concrete step with specific files/tables/endpoints]
+2. [Second step]
+3. [Third step]
+
+**Assumptions:**
+- [Specific technical assumption — e.g., "Column goes on the `transactions` table, not a new table"]
+- [Design assumption — e.g., "Enum values: duplicate, fraud, requested, other"]
+- [Scope assumption — e.g., "Admin detail view only, not the list view"]
+
+**Out of scope** (deferring these):
+- [Thing that's related but not part of this feature]
+
+Correct anything that's wrong, or confirm to proceed.
+```
+
+**Rules for assumptions:**
+- Be specific, not vague. "Add a column to the transactions table" not "update the database".
+- Reference actual file paths from the code you read.
+- Reference actual doc sections that inform your approach.
+- If the docs explicitly define a contract or scope boundary, follow it — don't assume differently.
+- If something is listed as "Out of Scope" in the module docs, it's out of scope for this feature too.
+
+**Wait for the user to confirm or correct before proceeding to Phase 4.**
+
+## Phase 4: Capture Decisions
+
+After the user confirms (or corrects) your assumptions, write the decisions file.
+
+Create the directory and file:
+```
+.context/<feature-id>/DECISIONS.md
+```
+
+Use a short, descriptive ID for the feature (e.g., `refund-reason`, `oauth-support`, `dashboard-charts`). If Beads is available (`bd` CLI), use the bead ID instead.
+
+**DECISIONS.md format:**
+
+```markdown
+# Decisions: <Feature Name>
+
+## Module
+<primary module> (+ secondary modules if cross-module)
+
+## Locked
+- [Decision 1 — specific, actionable]
+- [Decision 2]
+- [Decision 3]
+
+## Claude's Discretion
+- [Things the agent can decide — naming, file organization, minor implementation details]
+
+## Deferred
+- [Related work explicitly not part of this feature]
+
+## References
+- [Doc page read: docs/src/content/<module>/index.mdx]
+- [Doc page read: docs/src/content/<module>/<sub>.mdx]
+- [Code read: packages/<module>/src/<file>.ts]
+```
+
+## Phase 5: Create the Plan
+
+Write an execution plan with goal-backward success criteria.
+
+Create:
+```
+.context/<feature-id>/PLAN.md
+```
+
+**PLAN.md format:**
+
+```markdown
+# Plan: <Feature Name>
+
+## Success Criteria
+
+What must be TRUE in the codebase when this feature is done. Each criterion is independently verifiable — a grep, a typecheck, a file existence check, or a test run.
+
+- [ ] [Criterion 1 — specific and checkable, e.g., "`refundReason` column exists on `transactions` table"]
+- [ ] [Criterion 2 — e.g., "POST /api/payments/refund accepts `reason` field and validates with Zod"]
+- [ ] [Criterion 3 — e.g., "Admin transaction detail page renders `RefundReasonBadge` component"]
+- [ ] [Criterion 4 — e.g., "Types exported from `@acme/shared`"]
+
+## Tasks
+
+### task-1: <Short description>
+**Files:** [list of files to read and modify]
+**Do:** [What to implement — specific enough that a fresh agent with no prior context can do it]
+**Verify:** [How to check this task is done — e.g., "pnpm typecheck passes", "column exists in schema"]
+
+### task-2: <Short description>
+**Files:** [list of files]
+**Do:** [What to implement]
+**Verify:** [How to check]
+**Depends on:** task-1
+
+### task-3: <Short description>
+**Files:** [list of files]
+**Do:** [What to implement]
+**Verify:** [How to check]
+**Depends on:** task-1, task-2
+```
+
+**Rules for plans:**
+
+1. **2-4 tasks.** If you need more, the feature should be split. Each task must fit in a fresh agent context.
+
+2. **File targets are explicit.** Every task lists exactly which files to read and modify. A fresh agent with no prior context should know exactly where to look.
+
+3. **Verification is concrete.** Not "verify it works" — rather "run `pnpm typecheck` and confirm no errors" or "grep for `refundReason` in `schema.ts`".
+
+4. **Dependencies are explicit.** If task-3 needs types from task-1, say so. Tasks without dependencies can run in parallel.
+
+5. **No scope reduction.** Every locked decision from DECISIONS.md must be covered by at least one task. If a decision can't be delivered, STOP and tell the user — don't silently simplify.
+
+6. **Each task produces a commit.** The task description should correspond to a single atomic commit. "Add column and update 3 API endpoints and redesign the UI" is too big.
+
+7. **Reference the docs.** If a task implements something described in the docs (a contract, a data model, an API shape), reference the doc page so the executor can read it.
+
+## Phase 6: Plan Check
+
+Before presenting the plan to the user, self-check:
+
+1. **Coverage check:** Read DECISIONS.md. For each locked decision, confirm at least one task delivers it. If any decision is uncovered, add a task or flag the gap.
+
+2. **Scope reduction check:** Re-read your plan. Are you delivering exactly what was decided, or a simplified version? Look for red flags:
+   - "Simplified version" / "basic implementation" / "v1" / "placeholder"
+   - Missing a decision from the locked list
+   - A task that says "will be wired later" or "can be added in a follow-up"
+   If any of these appear, revise the plan or split into phases.
+
+3. **Size check:** Each task should touch 1-5 files. If a task lists more than 5 files, split it.
+
+4. **Fresh agent test:** For each task, ask: "Could a fresh agent with no conversation history execute this task from the description alone?" If not, add more detail to the task description.
+
+## Phase 7: Present the Plan
+
+Show the user:
+
+1. The success criteria (what will be TRUE when done)
+2. The task breakdown (what each task does, in what order)
+3. Total number of tasks and estimated commits
+
+Ask:
+> Plan ready. Review the success criteria and tasks above. Confirm to proceed, or let me know what to adjust.
+
+**Small task detection:** If the plan has only 1 task touching 3 or fewer files, offer:
+> This is a small change. Want me to just do it now? (Skips /go, executes inline.)
+
+If the user confirms inline execution, execute the single task directly — make the changes, run the verification step, and commit. No need for `/go`.
+
+---
+
+## What This Skill Does NOT Do
+
+- **Does not write code.** That's `/go`.
+- **Does not create PRs.** That's `/pr`.
+- **Does not update docs.** That's `/docs`.
+- **Does not run without user confirmation.** The plan is always presented for approval.
+- **Does not invent architecture.** It reads docs and code to understand what exists, then plans within those boundaries.

package/skills/build/resources/plan-checker.md

@@ -0,0 +1,121 @@
+# Plan Checker
+
+You are a plan validation agent. Your job is to verify that an execution plan will deliver what was decided — before any code is written.
+
+## Input
+
+You will receive:
+1. `.context/<id>/DECISIONS.md` — the locked decisions
+2. `.context/<id>/PLAN.md` — the proposed execution plan
+
+## Checks
+
+### 1. Coverage Check
+
+For each locked decision in DECISIONS.md, find the task(s) in PLAN.md that deliver it.
+
+Output a coverage table:
+
+| Decision | Covered by | Status |
+|----------|-----------|--------|
+| refundReason enum column on transactions | task-1 | COVERED |
+| API accepts reason field | task-2 | COVERED |
+| Admin shows badge | task-3 | COVERED |
+| Types in @acme/shared | task-1 | COVERED |
+
+If any decision shows **NOT COVERED**, the plan fails.
+
+### 2. Scope Reduction Check
+
+Scan the plan for these red flags:
+- "simplified", "basic", "minimal", "v1", "placeholder", "stub"
+- "will be wired later", "follow-up", "future work", "can be added"
+- "for now" (implies temporary solution)
+- A task that partially implements a locked decision
+
+If any task delivers less than what the decision specifies, flag it:
+```
+SCOPE REDUCTION DETECTED:
+  Decision: "Admin transaction detail shows refund reason badge"
+  Task-3 says: "Add placeholder text for refund reason"
+  This is a simplification. The decision says badge, not placeholder text.
+```
+
+### 3. Size Check
+
+Each task should:
+- Touch 1-5 files (flag if more)
+- Correspond to a single atomic commit
+- Be executable by a fresh agent with no prior context
+
+Flag oversized tasks:
+```
+OVERSIZED TASK:
+  task-2 touches 8 files. Consider splitting into:
+  - task-2a: API endpoint changes (3 files)
+  - task-2b: Validation schema changes (3 files)
+  - task-2c: Test updates (2 files)
+```
+
+### 4. Fresh Agent Test
+
+For each task, check: does the description include enough context for a fresh agent?
+
+Required in each task:
+- Which files to read (not just modify)
+- What to implement (specific, not vague)
+- How to verify (concrete check, not "verify it works")
+
+Flag insufficient tasks:
+```
+INSUFFICIENT CONTEXT:
+  task-3 says "Add badge component" but doesn't specify:
+  - Which design system components to use
+  - Where in the page layout it goes
+  - What data it displays
+```
+
+### 5. Dependency Check
+
+Verify that task dependencies are correct:
+- If task-2 uses types created in task-1, task-2 must depend on task-1
+- If tasks are marked independent (no depends-on), verify they truly don't share state
+
+Flag missing dependencies:
+```
+MISSING DEPENDENCY:
+  task-3 modifies the API response shape (adding refundReason field)
+  task-4 reads the API response in the admin UI
+  task-4 should depend on task-3
+```
+
+## Output
+
+```
+## Plan Check Results
+
+### Coverage: PASS / FAIL
+[coverage table]
+
+### Scope Reduction: PASS / FAIL
+[any flags]
+
+### Task Size: PASS / FAIL
+[any flags]
+
+### Fresh Agent Test: PASS / FAIL
+[any flags]
+
+### Dependencies: PASS / FAIL
+[any flags]
+
+### Verdict: PASS / NEEDS REVISION
+
+[If NEEDS REVISION: specific changes required]
+```
+
+## Rules
+
+- Maximum 2 revision rounds. If the plan still fails after 2 revisions, escalate to the user.
+- Be strict on coverage and scope reduction. Be lenient on size and context (warn, don't fail).
+- Never suggest reducing scope to make the plan pass. If a decision can't be delivered, that's information for the user, not a reason to simplify.

package/skills/docs/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: docs
+description: >
+  Update documentation for completed work. Only updates docs for features that are
+  implemented and verified — never for planned or in-progress work. Use this skill
+  when the user says 'docs', '/docs', 'update docs', 'update documentation',
+  'sync docs', or after /review passes and before /pr.
+user-invocable: true
+---
+
+# /docs — Update Documentation
+
+You update documentation to reflect completed, verified work. Docs describe what the system IS — never what's planned.
+
+## Phase 0: Detect What Changed
+
+1. Get the diff to understand what code changed:
+   ```bash
+   git diff main...HEAD --stat
+   ```
+
+2. Read `.context/<feature-id>/DECISIONS.md` to understand the feature intent.
+
+3. Read `.context/<feature-id>/PLAN.md` for the success criteria — these tell you what was built.
+
+## Phase 1: Map Changes to Docs
+
+Identify which documentation pages are affected.
+
+1. **Read the module registry** (`ystack.config.json`) to find the module-to-doc mapping. Match changed file paths against module `scope` globs. If no registry exists, fall back to scanning `docs/src/content/_meta.ts`.
+
+2. **Map changed code paths to doc pages:**
+
+   | Code path pattern | Likely doc page |
+   |-------------------|----------------|
+   | `packages/<name>/` | `docs/src/content/<module>/` or `docs/src/content/shared/<name>/` |
+   | `apps/<name>/` | `docs/src/content/<module>/` |
+   | `packages/db/src/schema*` | Data model sections across affected modules |
+   | `apps/api/src/routes/` | API module + any module whose API changed |
+
+3. **Read the affected doc pages** before modifying them. Understand what's currently documented.
+
+## Phase 2: Update Affected Pages
+
+For each affected doc page, update ONLY the sections impacted by the new feature.
+
+**What to update:**
+
+| Change type | Doc section to update |
+|-------------|----------------------|
+| New database column/table | Data Model section — add to table/columns/notes table |
+| New API endpoint or field | Dependencies section — update "Provides" list, or relevant sub-module page |
+| New UI component or page | Sub-modules table — add or update entry |
+| New module dependency | Dependencies section — update "Needs" table |
+| Changed flow or behavior | Flows section — update Mermaid diagram and numbered explanation |
+| New sub-module | Sub-modules table + create new sub-module page if significant |
+
+**What NOT to update:**
+- Sections unrelated to the feature
+- "Purpose" section (unless the module's core responsibility changed)
+- "Team" section
+- "Scope" section (unless something moved in/out of scope)
+
+**Writing rules:**
+- Present tense, active voice: "The gateway normalizes messages" not "Messages will be normalized"
+- Purpose over implementation: describe what it does and why, not how the code works
+- No version language: no "v1", "v2", "Phase 1", "new", "recently added"
+- No planning language: no "planned", "coming soon", "TODO", "will be", "in progress"
+- Link, don't recap: reference other pages instead of repeating their content
+- Use cross-references: `[Module Name](/module-path)` for every module mention
+
+**Diagram rules (if updating Mermaid diagrams):**
+- Use the right type: `sequenceDiagram` for multi-actor flows, `graph TB/LR` for architecture, `erDiagram` for data models
+- Label edges: `-->|"what flows"|` not just `-->`
+- Keep under 20 nodes — split if bigger
+- Every diagram needs a text explanation below it
+
+## Phase 3: Update Navigation
+
+If you created a new doc page, update the navigation config for the docs framework in use:
+
+**Nextra** — add to `_meta.ts`:
+```typescript
+// docs/src/content/<module>/_meta.ts
+export default {
+  index: "Overview",
+  "existing-page": "Existing Page",
+  "new-page": "New Page",        // ← add here, object key order = sidebar order
+};
+```
+
+**Fumadocs** — add to `meta.json` or use frontmatter ordering:
+```json
+// content/docs/<module>/meta.json
+{
+  "pages": ["index", "existing-page", "new-page"]
+}
+```
+
+Check `ystack.config.json` `docs.framework` to know which format to use.
+
+## Phase 4: Update Structural Files
+
+If the feature changed module responsibilities, dependencies, or structure, also update:
+
+1. **`CLAUDE.md`** — if the Structure section or Commands changed
+2. **`AGENTS.md`** — mirror CLAUDE.md changes
+3. **Package-level `CLAUDE.md`** — if a package's responsibilities changed
+
+Most features don't require structural file updates. Only update these if the module's role or boundaries shifted.
+
+## Phase 5: Verify
+
+1. Check that all cross-reference links point to existing pages:
+   ```bash
+   # Extract links from updated docs and verify targets exist
+   grep -oP '\[.*?\]\((/[^)]+)\)' docs/src/content/<module>/*.mdx
+   ```
+
+2. Confirm no planning language leaked in:
+   ```bash
+   grep -i -E '(coming soon|planned|todo|will be|in progress|phase [0-9])' docs/src/content/<module>/*.mdx
+   ```
+
+3. Present a summary of what was updated:
+   ```
+   ## Documentation Updates
+
+   ### Modified
+   - docs/src/content/shared/payments/index.mdx
+     - Added `refundReason` to Data Model table
+     - Updated Refund Flow sub-module description
+
+   ### Created
+   - (none)
+
+   ### Structural files
+   - (no changes needed)
+   ```
+
+---
+
+## Delegating to Existing Skills
+
+If the project has its own documentation skills (e.g., `docs-update`, `docs-module`, `docs-page`), prefer delegating to them. They know the project-specific conventions.
+
+- **Updating existing pages** → delegate to `docs-update` if available
+- **Creating a new module's docs** → delegate to `docs-module` if available
+- **Writing a single new page** → delegate to `docs-page` if available
+
+If no project-specific doc skills exist, follow the process above.
+
+---
+
+## What This Skill Does NOT Do
+
+- **Does not document planned features.** Only completed, verified work.
+- **Does not rewrite entire pages.** Updates only affected sections.
+- **Does not create module scaffolds.** That's `/scaffold`.
+- **Does not create PRs.** That's `/pr`.