ystack 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 0.1.0 — 2026-04-09
+
+First public release. Claude Code only.
+
+### Features
+
+- **CLI** — `ystack create`, `init`, `update`, `remove` commands with interactive prompts (@clack/prompts)
+- **Skills** — `/build`, `/go`, `/review`, `/docs`, `/pr`, `/import`, `/scaffold`, `/address-review`
+- **Hooks** — context-monitor (tracks context usage), workflow-nudge (suggests `/build` when editing without a plan), session-start (shows ready front)
+- **Module registry** — `ystack.config.json` maps code scopes to doc pages and Beads epics
+- **Beads integration** — persistent task memory with epics, features, ready front, structured notes
+- **Docs support** — Nextra 4 and Fumadocs, framework-agnostic doc layer
+- **`ystack create`** — scaffolds a full monorepo (Turborepo, pnpm, Ultracite, TypeScript strict, docs site)
+- **`ystack init`** — adds ystack to an existing project with auto-detection of docs framework, monorepo tool, and Beads
+
+### Design
+
+- Three-layer architecture: Docs (what it is), Beads (what's done), Code (the implementation)
+- Doc-driven workflow: read spec, plan, execute, verify, update docs
+- Fresh subagent per task for context isolation
+- Wave-based parallel execution with dependency tracking
+- Goal-backward verification against success criteria

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yulong He
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LINTING.md

@@ -0,0 +1,198 @@
+# Agent Linting
+
+> **Status: Design Spec — Not Yet Implemented**
+> None of the agent lint rules, hook infrastructure (`hooks/agent-lint.js`), or per-skill `rules/*.json` files described below are built. This document is a design specification for a future version of ystack. v0.1 includes basic Claude Code hooks (context monitoring, file-count nudge) but not the structured rule system described here.
+
+## Two Types of Linting
+
+**Code linting** checks what the code looks like — formatting, syntax, style. Tools like Ultracite/Biome handle this. You configure it once and it covers all code. Adding a new feature doesn't mean adding new rules.
+
+**Agent linting** checks what the agent does — did it follow the process? Did it read the spec? Did it verify its work? This is the harness enforcing discipline on agent behavior, not code quality.
+
+Code linting is static. Agent linting grows with the harness. Each new skill or convention can ship with its own agent lint rule.
+
+## How Agent Linting Works
+
+Agent lint rules are implemented as Claude Code hooks — `PreToolUse` and `PostToolUse` checks in `.claude/settings.json`. They run automatically during agent execution, providing warnings or blocks at the right moment.
+
+```
+Agent tries to edit code
+  → PreToolUse hook fires
+  → Check: is there an active plan?
+  → No plan → soft warning: "Consider /build for tracked changes"
+  → Has plan → proceed
+```
+
+Rules come in two severities:
+
+- **Warn** — surface a message, let the agent continue. For nudges and best practices.
+- **Block** — prevent the action. For hard constraints that protect quality.
+
+## Core Rules
+
+These ship with ystack out of the box.
+
+### Workflow Rules
+
+| Rule | Severity | When | What it checks |
+|------|----------|------|---------------|
+| `plan-before-edit` | Warn | PreToolUse on Edit | Is there an active `.context/<bead-id>/PLAN.md`? Nudges toward `/build` or `/quick`. |
+| `spec-before-plan` | Block | During `/build` | Did the agent read the module's doc page before creating a plan? Prevents hallucinated architecture. |
+| `decisions-before-execute` | Block | During `/go` | Does `.context/<bead-id>/DECISIONS.md` exist? No executing without confirmed decisions. |
+| `plan-checker-passed` | Block | During `/go` | Has the plan-checker agent validated the plan? No executing unchecked plans. |
+| `no-scope-reduction` | Block | During `/plan` | Does the plan cover ALL locked decisions from DECISIONS.md? Catches silent simplification. |
+
+### Verification Rules
+
+| Rule | Severity | When | What it checks |
+|------|----------|------|---------------|
+| `verify-before-ship` | Block | During `/pr` | Has `/review` passed all success criteria? No shipping unverified work. |
+| `docs-before-ship` | Warn | During `/pr` | Are there closed beads without corresponding doc updates? Nudges toward `/docs`. |
+| `typecheck-before-ship` | Block | During `/pr` | Does `pnpm typecheck` pass? No shipping broken types. |
+
+### Documentation Rules
+
+| Rule | Severity | When | What it checks |
+|------|----------|------|---------------|
+| `cross-references` | Warn | During `/docs` | Does the updated doc page link to related modules? Flags isolated pages. |
+| `final-state-only` | Block | During `/docs` | Does the doc contain "planned", "coming soon", "TODO", "WIP"? Docs describe what IS. |
+| `module-registered` | Warn | During `/build` | Is the target module in `ystack.config.json`? Catches work outside any module's scope. |
+
+### Context Rules
+
+| Rule | Severity | When | What it checks |
+|------|----------|------|---------------|
+| `context-budget` | Warn | PostToolUse | Is context usage above 60%? Suggests spawning subagents. |
+| `context-critical` | Warn | PostToolUse | Is context usage above 80%? Suggests finishing current task or `/pause`. |
+| `reference-not-dump` | Warn | During `/build` | Did the agent inline a full doc page into the plan instead of referencing it? |
+
+## Adding Rules When You Add Skills
+
+Each skill can ship with its own lint rules. When you install a skill, its rules get added to the hook configuration automatically.
+
+**Example: adding a `/test` skill**
+
+The skill comes with:
+```
+skills/test/
+├── SKILL.md
+└── rules/
+    └── tests-before-ship.json
+```
+
+The rule definition:
+```json
+{
+  "name": "tests-before-ship",
+  "severity": "warn",
+  "hook": "PreToolUse",
+  "trigger": "during /pr",
+  "check": "Do test files exist for changed modules?",
+  "message": "Changed modules have no tests. Consider /test before shipping."
+}
+```
+
+On install, this gets wired into `.claude/settings.json` alongside the skill.
+
+## Rule Lifecycle
+
+Rules evolve with the project:
+
+1. **Start soft.** New rules ship as `warn`. Teams adopt the practice before it becomes enforced.
+2. **Promote to block.** Once the team is comfortable, flip severity to `block` for critical rules.
+3. **Project-specific rules.** Teams can add their own rules in `ystack.config.json`:
+
+```json
+{
+  "linting": {
+    "rules": {
+      "plan-before-edit": "warn",
+      "spec-before-plan": "block",
+      "verify-before-ship": "block",
+      "docs-before-ship": "warn",
+      "cross-references": "warn",
+      "custom-rules": [
+        {
+          "name": "security-review-for-auth",
+          "severity": "block",
+          "trigger": "during /pr",
+          "check": "If changed packages include 'auth', has a security-focused review been done?",
+          "message": "Auth changes require security review. Run /review --security first."
+        }
+      ]
+    }
+  }
+}
+```
+
+4. **Disable rules.** Any rule can be turned off per-project:
+
+```json
+{
+  "linting": {
+    "rules": {
+      "context-budget": "off"
+    }
+  }
+}
+```
+
+## Implementation
+
+Agent lint rules are thin hooks. Each rule is a single check that runs at a specific point in the workflow.
+
+### Hook Structure
+
+```javascript
+// hooks/agent-lint.js
+// PostToolUse hook — runs after every tool call
+
+export default function agentLint({ tool, input, output, config }) {
+  const rules = loadRules(config);
+  const violations = [];
+
+  for (const rule of rules) {
+    if (rule.shouldRun(tool, input)) {
+      const result = rule.check(tool, input, output);
+      if (result.violated) {
+        violations.push({
+          rule: rule.name,
+          severity: rule.severity,
+          message: result.message
+        });
+      }
+    }
+  }
+
+  // Warnings get surfaced as messages
+  // Blocks prevent the action
+  return formatViolations(violations);
+}
+```
+
+### What Rules Can Check
+
+Rules have access to:
+- **Tool name and input** — which tool was called and with what arguments
+- **File system** — read `.context/`, `ystack.config.json`, doc pages
+- **Beads state** — `bd show`, `bd ready` (via shell)
+- **Git state** — current diff, branch, recent commits
+
+Rules do NOT:
+- Modify files
+- Call external APIs
+- Block indefinitely
+- Access conversation history
+
+## Code Linting vs. Agent Linting
+
+| | Code Linting | Agent Linting |
+|---|---|---|
+| **Tool** | Ultracite / Biome | ystack hooks |
+| **Checks** | Formatting, syntax, style | Process, workflow, constraints |
+| **When** | Pre-commit hook | During agent execution |
+| **Grows with** | Language features | New skills and conventions |
+| **Examples** | "Use `const` not `let`" | "Read the spec before planning" |
+| **Configured in** | `biome.json` | `ystack.config.json` |
+
+Both run automatically. Code linting on commit, agent linting during workflow. Together they ensure both the code and the process that produced it meet the team's standards.

package/PHILOSOPHY.md

@@ -0,0 +1,132 @@
+# Design Philosophy
+
+## The Five Constraints
+
+The harness enforces five things on every agent interaction:
+
+1. **Read the spec first.** Before writing code, the agent reads the relevant doc page. No guessing.
+2. **Plan before executing.** The agent shows you what it will do. You confirm or correct.
+3. **Verify against criteria.** After execution, goal-backward verification checks the codebase — "does this column exist? Is this endpoint wired?" — not "did the task complete?"
+4. **Never simplify silently.** If the plan can't deliver what was decided, it splits into phases instead of cutting corners.
+5. **Update docs when done.** Documentation reflects the new reality before the PR is created.
+
+The harness also includes [agent linting](./LINTING.md) — rules that check agent behavior, not code style. Did the agent read the spec? Does the plan cover all decisions? Are docs updated? These rules grow with the harness: each new skill can ship its own lint rules.
+
+## Documentation as the Operating System
+
+Most teams treat documentation as a chore — something you write after the code is done, if you write it at all. ystack treats documentation as the operating system for your entire development process.
+
+When you write a doc page for a module, that page becomes:
+- The **spec** your AI agent reads before writing code
+- The **reference** your team reads to understand the system
+- The **context** a new developer uses to get up to speed
+- The **contract** between modules that defines boundaries
+
+You write it once. It serves all four purposes. There is no separate "planning doc" and "user doc" and "AI context file" — they are the same document.
+
+## Three Layers, Three Roles
+
+```
+Docs        →  What the system IS (final state)
+Beads       →  What's been done, what's left (development state)
+Code        →  The actual implementation
+```
+
+These three layers never overlap in responsibility:
+
+**Docs** describe the finished design. They answer: what does this module do? How does it connect to other modules? What data does it manage? What are the contracts at its boundaries? Docs never contain "planned", "coming soon", "TODO", or "v2". If it's in the docs, it's built and working.
+
+**Beads** tracks the journey. It knows which features are implemented, which are in progress, which are blocked. It holds the structured notes that let an agent resume work after a context reset. It manages dependencies between tasks. Beads is the development state machine — it knows where you are in the process.
+
+**Code** is the implementation. It doesn't need to explain itself beyond what's necessary for maintenance. The architecture lives in docs. The progress lives in Beads. The code just works.
+
+## Why Human-Readable Markdown
+
+AI agents work better with clean, structured prose than with machine-generated metadata blobs. A well-written doc page gives an agent:
+
+- **Selective context** — read only the page you need, not a 500-line dump
+- **Navigable structure** — headings, sections, and cross-references let the agent find exactly what's relevant
+- **Accurate mental model** — prose written for humans forces clarity that JSON schemas don't
+
+This is why ystack works with documentation frameworks like Nextra and Fumadocs. The docs are rendered as a real documentation site that humans browse. The same markdown files are what AI agents read as context. The format that's good for humans turns out to be good for agents too.
+
+The alternative — generating machine-readable context files, planning artifacts, or structured metadata — creates information that's useful to nobody except the tool that generated it. It rots quickly, nobody maintains it, and it bloats agent context with noise.
+
+## References, Not Dumps
+
+When an agent needs to understand the payments module, ystack tells it: "Read `docs/src/content/shared/payments.mdx`." It does not paste the entire page into the prompt.
+
+This matters because:
+
+1. **Context windows are finite.** Every token of inlined content is a token you can't use for reasoning.
+2. **Docs change.** A reference always points to the current version. Inlined content is stale the moment it's pasted.
+3. **Agents can navigate.** A doc page with cross-references lets the agent follow links to related modules, just like a human developer would.
+
+The module registry (`ystack.config.json`) exists to give agents a map: "payments lives here in the code, here in the docs, and here in Beads." From that map, the agent reads what it needs, when it needs it.
+
+## Connected Documentation
+
+Every doc page should be highly connected to related pages. Cross-references are not optional — they are how agents (and humans) navigate the system.
+
+A module overview page should link to:
+- Its sub-module pages (detailed specs for each component)
+- Modules it depends on (upstream contracts it relies on)
+- Modules that depend on it (downstream consumers)
+- Data model pages (shared schema definitions)
+- The system architecture page (where it fits in the big picture)
+
+When an agent reads a module page and finds a reference to another module, it can follow that link to understand the boundary. This is how agents build understanding incrementally — by navigating a graph of connected documents, not by receiving a monolithic context dump.
+
+The navigation structure (framework-specific: `_meta.ts` in Nextra, `meta.json` in Fumadocs) defines the hierarchy. Cross-references within page content define the graph. Together they create a documentation site that works as both a human-readable reference and an agent-navigable knowledge base.
+
+## The Module Registry
+
+The module registry bridges three worlds:
+
+```json
+{
+  "payments": {
+    "doc": "shared/payments",
+    "scope": [
+      "packages/payments/**",
+      "packages/db/src/schema/transactions.*",
+      "apps/api/src/routes/payments.*"
+    ],
+    "epic": "bd-a1b2"
+  }
+}
+```
+
+- **doc** → where to read the spec (and where to write updates when features complete)
+- **scope** → where the code lives, as glob patterns. A module doesn't have to be a package — it can span files across multiple packages, or live within a subdirectory of one. This is what to scan when planning and what to verify when done.
+- **epic** → where progress lives (which features are built, which are pending)
+
+The registry tracks **modules only**. Sub-modules are tracked by the docs site (sub-pages within a module). Features are tracked by Beads (child beads under the module's epic). Each layer has its own hierarchy — the registry connects the top level.
+
+When a Beads epic's child closes, ystack knows which doc page might need updating. When `/build` starts planning, it knows which files across the repo are relevant. When `/import` scans an existing repo, it builds this map automatically.
+
+The registry is small, stable, and rarely changes. It's the index — the docs, code, and beads are the content.
+
+## Documentation Reflects Only Completed Work
+
+This is a hard rule. Docs describe what IS, never what's planned.
+
+When you run `/scaffold` to start a new project, it creates doc stubs — module overviews with interaction diagrams and section headers. These stubs show structure (what modules exist and how they connect) but not implementation detail. The detail gets filled in by `/docs` as features are completed and verified.
+
+This means:
+- A new team member reading the docs sees exactly what's built and working
+- An agent reading the docs gets accurate context, not aspirational specs
+- There's no "planned" section that's been "planned" for six months
+- The gap between docs and reality is always zero for documented features
+
+Beads tracks what's planned and in progress. That's its job. Docs track what's done. The boundary is clean.
+
+## Why This Works for Teams
+
+A developer joins the project. They read the docs site. They understand the architecture, the module boundaries, the data models, the contracts. Everything they read is accurate because it describes completed, verified work.
+
+They pick up a feature. `/build` reads the same docs to understand context. The agent and the developer are reading the same source of truth. The agent creates a plan grounded in real architecture, not hallucinated structure.
+
+They finish the feature. `/docs` updates the relevant pages. The docs site now reflects the new reality. The next developer — or the next agent session — gets accurate context automatically.
+
+No one wrote documentation as a separate task. The docs updated as a natural step in the workflow. The documentation site is always current because it's part of the development process, not an afterthought.