ystack 0.1.0

package/skills/go/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: go
+description: >
+  Execute a plan created by /build. Runs each task with a fresh subagent, produces
+  atomic commits, and updates structured notes. Use this skill when the user says
+  'go', '/go', 'execute', 'run the plan', 'execute the plan', 'start building',
+  'let's do it', or confirms a plan and wants to proceed with implementation.
+  Requires a PLAN.md from a prior /build run.
+user-invocable: true
+---
+
+# /go — Execute the Plan
+
+You are the execution phase of the ystack agent harness. You take a PLAN.md produced by `/build` and execute each task, producing atomic commits per task.
+
+**Your job is to implement, not to redesign.** Follow the plan. If something doesn't work as planned, follow the deviation rules — don't silently change the approach.
+
+## Phase 0: Load the Plan
+
+1. Find the active plan. Look for `.context/` directories with a PLAN.md:
+   ```bash
+   ls .context/*/PLAN.md 2>/dev/null
+   ```
+
+2. If multiple plans exist, list them and ask which to execute:
+   > Found plans for:
+   > - `refund-reason` — Add refund reason to payments (3 tasks)
+   > - `oauth-support` — Add OAuth to auth module (4 tasks)
+   >
+   > Which plan should I execute?
+
+3. If no plan exists:
+   > No plan found. Run `/build <feature>` first to create one.
+
+4. Read the full PLAN.md and DECISIONS.md for context:
+   ```
+   .context/<feature-id>/PLAN.md
+   .context/<feature-id>/DECISIONS.md
+   ```
+
+5. Parse the plan: extract success criteria, tasks, file targets, dependencies, and verification steps.
+
+## Phase 1: Compute Execution Order
+
+Determine which tasks can run and in what order.
+
+1. **Build the dependency graph** from `Depends on:` fields in each task.
+
+2. **Group into waves:**
+   - **Wave 1:** Tasks with no dependencies (can run in parallel)
+   - **Wave 2:** Tasks that depend only on Wave 1 tasks
+   - **Wave 3:** Tasks that depend on Wave 1 or 2 tasks
+   - etc.
+
+3. **Present the execution order:**
+   ```
+   Execution order:
+     Wave 1: task-1 (Schema and types)
+     Wave 2: task-2 (API endpoint), task-3 (Validation)
+     Wave 3: task-4 (Admin UI) — depends on task-2
+   ```
+
+4. Proceed immediately — no confirmation needed (the user already approved the plan in `/build`).
+
+## Phase 2: Execute Tasks
+
+For each wave, execute all tasks in the wave. Within a wave, tasks are independent and can run in parallel (if the runtime supports subagents).
+
+### Per-task execution:
+
+**Step 1: Read context**
+
+Read ONLY the files listed in the task's `Files:` field. If the task references a doc page, read that too. Do not read unrelated files — the plan already scoped what matters.
+
+Also read:
+- DECISIONS.md — for the locked decisions relevant to this task
+- Any files produced by prior tasks in earlier waves (new types, new schemas)
+
+**Step 2: Implement**
+
+Follow the task's `Do:` field exactly. Write the code.
+
+Rules:
+- Implement what the task says. Not more, not less.
+- Follow existing code patterns in the files you're modifying. Match style, naming, imports.
+- If the task references a doc page contract (e.g., "API shape defined in docs"), implement exactly what the docs specify.
+- Run the project linter if available (`pnpm fix`, `ultracite fix`, or equivalent) after making changes.
+
+**Step 3: Verify**
+
+Run the task's `Verify:` step. Common verification patterns:
+
+- `pnpm typecheck` — types compile
+- `pnpm check` — lint passes
+- Grep for expected patterns — `grep -r "refundReason" packages/db/src/schema.ts`
+- File existence — `ls packages/shared/src/types/payments.ts`
+- Test execution — `pnpm test --filter=<package>`
+
+If verification fails, fix the issue and re-verify. Do not skip verification.
+
+**Step 4: Commit**
+
+Create an atomic commit for this task. Use Conventional Commits format:
+
+```
+<type>(<scope>): <description>
+```
+
+Where:
+- `type` = `feat`, `fix`, `refactor`, `chore`, `test` (match the nature of the change)
+- `scope` = the package or module affected (e.g., `db`, `api`, `admin`, `shared`)
+- `description` = what changed, in imperative mood
+
+Stage only the files this task modified. Do not stage unrelated changes.
+
+**Step 5: Update notes**
+
+If Beads is available (`bd` CLI), update the bead's structured notes:
+```bash
+bd update <bead-id> --notes "COMPLETED: <what was done>
+KEY DECISIONS: <any implementation decisions made>"
+bd close <bead-id> --reason "<summary>"
+```
+
+If Beads is not available, append to a `SUMMARY.md` in the feature's `.context/` directory.
+
+### Subagent execution (Tier 1 runtimes)
+
+On runtimes that support subagents (Claude Code, Gemini CLI), each task SHOULD be executed by a fresh subagent. This prevents context rot — the subagent gets a clean context window with only the task description and file targets.
+
+Spawn the subagent with:
+- The task description (Do, Files, Verify fields)
+- The relevant locked decisions from DECISIONS.md
+- Any doc page references from the task
+- The executor agent prompt from `resources/executor.md`
+
+After the subagent completes, verify its work in the orchestrator context before moving to the next wave.
+
+### Inline execution (Tier 2+ runtimes or small plans)
+
+On runtimes without subagent support, or when the plan has only 1-2 tasks, execute tasks directly in the current context. Same steps, just no context isolation.
+
+## Phase 3: Handle Deviations
+
+During execution, you may encounter situations the plan didn't anticipate. Follow these rules strictly:
+
+### Rule 1: Auto-fix — Minor bugs in existing code
+> While modifying `payments.ts`, you notice an unused import.
+
+**Action:** Fix it silently. Include in the same commit. Not worth stopping for.
+
+### Rule 2: Auto-fix — Missing critical functionality
+> The task says "add Zod validation" but the file doesn't import Zod yet.
+
+**Action:** Add the import. This is implied by the task. Include in the same commit.
+
+### Rule 3: Auto-fix — Blocking issues in adjacent code
+> The task depends on a type that has a typo in its definition, causing typecheck to fail.
+
+**Action:** Fix the typo. Note it in the commit message. It's blocking your task.
+
+### Rule 4: STOP — Architectural decisions
+> The task says "add column to transactions table" but you discover transactions is actually a view, not a table.
+
+**Action:** STOP execution. Report the issue to the user:
+> **Deviation detected in task-2:**
+> The plan assumes `transactions` is a table, but it's a view over `transaction_log`.
+> Adding a column requires modifying the underlying table instead.
+>
+> Options:
+> 1. Add the column to `transaction_log` and update the view
+> 2. Revise the plan
+> 3. Skip this task and continue with others
+
+Wait for user decision before proceeding.
+
+### Rule 5: STOP — Scope change
+> While implementing, you realize the feature needs a database migration that wasn't in the plan.
+
+**Action:** STOP. Report to the user. A migration is a significant scope addition — the user should decide.
+
+## Phase 4: Report Results
+
+After all tasks complete (or if execution stops due to a deviation), report:
+
+```
+## Execution Summary
+
+### Completed
+- task-1: Schema and types ✓ (commit: abc1234)
+- task-2: API endpoint ✓ (commit: def5678)
+- task-3: Admin UI ✓ (commit: ghi9012)
+
+### Verification
+- pnpm typecheck: PASS
+- pnpm check: PASS
+
+### Notes
+- [Any deviations, auto-fixes, or observations worth mentioning]
+
+### Next Steps
+- Run /review to verify against success criteria
+- Run /docs if documentation needs updating
+```
+
+Write this summary to `.context/<feature-id>/SUMMARY.md`.
+
+---
+
+## What This Skill Does NOT Do
+
+- **Does not create plans.** That's `/build`. If no PLAN.md exists, say so.
+- **Does not redesign.** Follow the plan. Deviations go through the deviation rules.
+- **Does not update docs.** That's `/docs`.
+- **Does not create PRs.** That's `/pr`.
+- **Does not skip verification.** Every task's Verify step must run.

package/skills/go/resources/executor.md

@@ -0,0 +1,57 @@
+# Task Executor
+
+You are a task execution agent. You receive a single task from an execution plan and implement it. You have a fresh context window — no prior conversation history.
+
+## Input
+
+You will receive:
+- A task description with `Files`, `Do`, and `Verify` fields
+- Relevant locked decisions from DECISIONS.md
+- Optional: doc page references to read for contracts and specs
+
+## Process
+
+1. **Read files.** Read every file listed in the `Files` field. Understand the existing code before modifying it.
+
+2. **Read decisions.** Check the locked decisions for anything relevant to this task. Follow them exactly.
+
+3. **Read docs.** If the task references a doc page, read it. The docs define the contracts — implement what they specify.
+
+4. **Implement.** Follow the `Do` field. Write code that:
+   - Matches the existing style in the files you're modifying
+   - Uses the same patterns (imports, naming, error handling)
+   - Follows the locked decisions
+   - Does exactly what the task says — not more, not less
+
+5. **Lint.** Run the project linter if available (`pnpm fix` or equivalent).
+
+6. **Verify.** Run the `Verify` step. If it fails, fix and re-verify.
+
+7. **Report.** When done, output:
+   ```
+   ## Task Complete
+
+   ### What was done
+   - [Specific changes made]
+
+   ### Files modified
+   - [list of files]
+
+   ### Verification
+   - [verification step]: PASS/FAIL
+
+   ### Decisions applied
+   - [which locked decisions informed the implementation]
+
+   ### Notes
+   - [anything unexpected, auto-fixes applied, observations]
+   ```
+
+## Rules
+
+- You implement ONE task. Do not look at other tasks in the plan.
+- Do not modify files outside your `Files` list unless absolutely necessary (e.g., a shared import file).
+- If you encounter something that contradicts the task description, STOP and report it — do not silently work around it.
+- Match existing code patterns. If the codebase uses arrow functions, use arrow functions. If it uses `for...of`, use `for...of`. Don't introduce new patterns.
+- Do not add comments explaining your changes. The commit message handles that.
+- Do not add error handling, validation, or features beyond what the task specifies.

package/skills/import/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: import
+description: >
+  Analyze an existing codebase and generate a ystack module registry, Beads epics,
+  and a documentation gap report. Use this skill when the user says 'import', '/import',
+  'adopt this project', 'onboard this repo', 'scan the codebase', 'set up ystack here',
+  or when adding ystack to a project that already has code and possibly docs.
+  Supports incremental adoption with --module flag.
+user-invocable: true
+---
+
+# /import — Adopt an Existing Project
+
+You analyze an existing codebase and produce a module registry, Beads epics, and a gap report. This is the on-ramp for projects that already have code.
+
+**You do NOT modify code or docs.** You produce a registry and report. The user decides what to act on.
+
+## Phase 0: Determine Scope
+
+1. Check if `ystack.config.json` already exists:
+   ```bash
+   cat ystack.config.json 2>/dev/null
+   ```
+
+2. If a `--module <name>` argument was provided, scope the import to that module only. Otherwise, scan the entire repo.
+
+3. If the config already has modules registered, note which are new vs. already known.
+
+## Phase 1: Scan the Codebase
+
+Analyze the repo structure to detect logical modules. Spawn parallel research for each area:
+
+### 1a: Structure scan
+
+Map the directory tree to identify module boundaries:
+```bash
+# Find package.json files (monorepo packages)
+find . -name "package.json" -not -path "*/node_modules/*" -maxdepth 3
+
+# Get directory structure
+ls -d apps/*/ packages/*/ 2>/dev/null
+
+# Check for monorepo config
+cat turbo.json 2>/dev/null
+cat pnpm-workspace.yaml 2>/dev/null
+cat lerna.json 2>/dev/null
+```
+
+Classify each directory:
+- `apps/*` → likely an app module (UI, server, API)
+- `packages/*` → likely a library package
+- `src/modules/*` or `src/features/*` → feature-based structure (single-app repo)
+- Top-level `src/` without sub-packages → single-module project
+
+### 1b: Dependency scan
+
+Map imports between modules to understand connections:
+```bash
+# Find cross-package imports
+grep -r "from ['\"]@" packages/ apps/ --include="*.ts" --include="*.tsx" -l 2>/dev/null
+
+# Check package.json dependencies for workspace references
+cat packages/*/package.json | grep "workspace:" 2>/dev/null
+```
+
+Build a dependency graph: which modules import from which.
+
+### 1c: Schema scan
+
+Identify data models, API routes, and type definitions:
+```bash
+# Database schemas
+find . -path "*/schema*" -name "*.ts" -not -path "*/node_modules/*" 2>/dev/null
+find . -path "*/migrations*" -not -path "*/node_modules/*" -type d 2>/dev/null
+
+# API routes
+find . -path "*/routes/*" -o -path "*/api/*" -name "*.ts" -not -path "*/node_modules/*" 2>/dev/null
+
+# Shared types
+find . -path "*/types/*" -name "*.ts" -not -path "*/node_modules/*" 2>/dev/null
+```
+
+### 1d: Docs scan
+
+Find existing documentation and map it to modules:
+```bash
+# Nextra
+ls docs/src/content/_meta.ts 2>/dev/null && find docs/src/content -name "*.mdx" -o -name "*.md" 2>/dev/null
+
+# Fumadocs
+ls content/docs/meta.json 2>/dev/null && find content/docs -name "*.mdx" -o -name "*.md" 2>/dev/null
+
+# Generic docs
+ls docs/ README.md CLAUDE.md AGENTS.md 2>/dev/null
+```
+
+Read `_meta.ts` or `meta.json` files to understand the doc site structure. Read `CLAUDE.md` and `AGENTS.md` for project context.
+
+## Phase 2: Detect Modules
+
+Group the scan results into logical modules.
+
+### Grouping rules
+
+1. **Monorepo packages** — each `apps/` and `packages/` directory is a candidate module.
+
+2. **Cross-cutting modules** — some modules span multiple packages. Look for:
+   - A package that has schema files in `packages/db/` AND routes in `apps/api/` AND UI in `apps/admin/` → likely one module with scope across all three
+   - Shared types that are consumed by multiple packages → the types belong to whichever module defines the domain
+
+3. **Feature modules within a package** — a large package might contain multiple modules:
+   - `packages/core/src/features/onboarding/index.ts` → could be its own sub-module
+   - Only split if the docs site treats it as a separate section
+
+4. **Infrastructure vs. domain** — separate infrastructure (db, shared, tsconfig) from domain modules (payments, auth, dashboard). Infrastructure packages are usually not their own modules unless the docs site documents them.
+
+### Module detection output
+
+For each detected module, determine:
+- **Name** — human-readable identifier
+- **Scope** — glob patterns for files that belong to this module
+- **Doc page** — matching docs path (if docs exist) or `null`
+- **Status** — `implemented` (has code), `documented` (has docs), `both`, or `gap`
+- **Features** — key files/exports that represent implemented features
+- **Dependencies** — other modules this one imports from
+
+### Present findings
+
+```
+## Detected Modules (8)
+
+| Module | Scope | Docs | Status |
+|--------|-------|------|--------|
+| payments | packages/payments/**, apps/api/src/routes/payments.* | shared/payments | both |
+| auth | packages/shared/src/auth/**, apps/api/src/routes/auth.* | shared/authentication | both |
+| dashboard | apps/dashboard/** | dashboard | both |
+| admin | apps/admin/** | admin-dashboard | docs only (stub) |
+| notifications | packages/notifications/** | notifications | both |
+| billing | packages/billing/** | billing | code only (no docs) |
+| db | packages/db/** | (infrastructure) | — |
+| shared | packages/shared/** | shared | partial |
+
+Connections:
+  payments → db, shared
+  dashboard → payments, billing, notifications, db
+  admin → payments, dashboard, billing
+  ...
+
+Does this look right? I'll generate the registry from this.
+```
+
+**Wait for user confirmation.** The user may want to merge, split, or rename modules.
+
+## Phase 3: Generate Module Registry
+
+Create or update `ystack.config.json`:
+
+```json
+{
+  "project": "<detected-project-name>",
+  "docs": {
+    "root": "<detected-docs-root>",
+    "framework": "<nextra|fumadocs|unknown>"
+  },
+  "modules": {
+    "payments": {
+      "doc": "shared/payments",
+      "scope": [
+        "packages/payments/**",
+        "packages/db/src/schema/transactions.*",
+        "apps/api/src/routes/payments.*"
+      ],
+      "status": "active"
+    }
+  }
+}
+```
+
+For each module:
+- `doc` — the matching docs path, or `null` if no docs exist
+- `scope` — glob patterns covering all files that belong to this module
+- `status` — `"active"` if code exists, `"planned"` if only docs/stubs
+
+If the config already exists, merge new modules — don't overwrite existing entries.
+
+## Phase 4: Create Beads Epics
+
+If Beads (`bd`) is available:
+
+1. Create an epic per module:
+   ```bash
+   bd create "<Module Name>" -t epic --metadata '{"doc": "<module-slug>", "ystack": true}'
+   ```
+
+2. For each implemented feature detected in the code, create a **closed** child bead:
+   ```bash
+   bd create "<Feature description>" -t feature --parent <epic-id>
+   bd close <bead-id> --reason "Pre-existing implementation detected by /import"
+   ```
+
+3. Add inter-module dependencies:
+   ```bash
+   bd dep add <epic-id> related:<dependent-epic-id>
+   ```
+
+4. Update `ystack.config.json` with epic IDs.
+
+If Beads is not available, skip and note:
+> Beads not detected. Run `bd init` to enable progress tracking.
+
+## Phase 5: Generate Gap Report
+
+Analyze the delta between code and docs:
+
+```markdown
+## Import Report
+
+### Project: <name>
+### Modules: N detected, M documented
+
+---
+
+### Fully Documented (N)
+- payments — docs match implementation
+- auth — docs match implementation
+
+### Code Without Docs (N)
+- billing — 5 features implemented, no doc pages
+  - Invoice generation
+  - Subscription management
+  - Usage metering
+  - Refund processing
+  - Payment method CRUD
+
+### Docs Without Code (N)
+- admin/analytics — doc page exists but feature not implemented
+
+### Stale Docs (N)
+- shared/storage — docs reference old S3 API, code uses R2 SDK
+  Evidence: docs mention `@aws-sdk/client-s3`, code imports `@acme/shared/storage`
+
+### Missing Cross-References (N)
+- dashboard/index.mdx mentions "Payments" but doesn't link to /shared/payments
+- billing has no doc page, so nothing can link to it
+
+---
+
+### Recommended Next Steps
+1. Run `/scaffold` or `/docs` to create docs for billing (5 undocumented features)
+2. Update shared/storage docs (stale — S3 → R2 migration)
+3. Add cross-reference links in dashboard/index.mdx
+4. `/build` for any new features — the registry is ready
+```
+
+### Stale docs detection
+
+Compare code and docs for inconsistencies:
+- **Imports in docs vs. code** — do docs reference packages the code no longer uses?
+- **API routes** — do docs describe endpoints that don't exist (or miss ones that do)?
+- **Schema fields** — do data model tables in docs match actual schema files?
+- **Module names** — do docs use old names for renamed modules?
+
+Only flag clear mismatches. Don't flag vague prose that's technically correct.
+
+## Phase 6: Summary
+
+```
+## Import Complete
+
+### Registry
+  ystack.config.json — N modules registered
+
+### Beads
+  N epics created, M features tracked (K pre-closed as implemented)
+
+### Documentation
+  N pages found, M gaps detected
+
+### Next Steps
+  - Fix N doc gaps with /docs or /scaffold
+  - Run /build to start new feature work
+  - The module registry connects code ↔ docs ↔ beads
+```
+
+---
+
+## Incremental Adoption
+
+With `--module <name>`:
+
+1. Only scan files matching the specified module name or path
+2. Only create one module entry in the registry
+3. Only create one epic in Beads
+4. Gap report scoped to that module
+
+This is useful for large repos where a full scan is too slow, or when onboarding one team at a time.
+
+---
+
+## What This Skill Does NOT Do
+
+- **Does not modify code.** Read-only scan.
+- **Does not modify existing docs.** Reports gaps, doesn't fix them.
+- **Does not install tooling.** No Turborepo, Ultracite, Nextra — that's `npx ystack init` or `create`.
+- **Does not create doc pages.** Reports what's missing — `/docs` or `/scaffold` creates them.
+- **Does not guess features.** Only reports what it can detect from code structure, exports, and file names.