ystack 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.2.0 — 2026-04-09
+
+**Breaking:** Replaces Beads with git-native progress files. No migration path from 0.1.0 — run `npx ystack init` to set up the new `.ystack/` directory.
+
+### Breaking Changes
+
+- `ystack.config.json` moved to `.ystack/config.json`
+- `.beads/` directory no longer used — progress tracked in `.ystack/progress/*.md`
+- `"epic"` field removed from module registry entries
+- `.context/<bead-id>/` renamed to `.context/<feature-slug>/`
+- `bd` CLI no longer required
+
+### Added
+
+- **`/quick` skill** — fast path for bug fixes, chores, and small changes (skips planning and progress)
+- **`progress-before-ship` hook** — warns on PR if code changed but progress not updated
+- **`docs-match-progress` hook** — catches `[x]` items with stubbed doc sections
+- **`no-undocumented-check` hook** — warns when checking a box with stub docs still present
+- **`/pr` runs `/docs` inline** when it detects stubbed doc sections for completed features
+
+### Changed
+
+- Progress tracked via markdown checklists in `.ystack/progress/<module>.md` instead of Beads
+- `workflow-nudge` hook now recognizes `/quick` mode and stays silent
+- `progress-before-ship` hook skips warning for small diffs (5 or fewer code files)
+- `session-start` hook reads `.ystack/progress/` instead of `bd ready`
+
+### Removed
+
+- Beads (`bd` CLI) dependency
+- `PLAN.md` project roadmap (content lives in individual skill files)
+- Beads installation flow from `ystack init` and `ystack create`
+
+---
+
 ## 0.1.0 — 2026-04-09
 
 First public release. Claude Code only.
@@ -8,7 +43,7 @@ First public release. Claude Code only.
 
 - **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)
+- **Hooks** — context-monitor, workflow-nudge, session-start
 - **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

package/LINTING.md

@@ -1,8 +1,5 @@
 # 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.
@@ -28,44 +25,61 @@ 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
+---
+
+## Built Hooks
+
+These are implemented and installed by `npx ystack init`.
+
+### Workflow Hooks
+
+| Hook | File | Trigger | What it does |
+|------|------|---------|-------------|
+| **workflow-nudge** | `workflow-nudge.js` | PreToolUse on Edit/Write | After 3+ source files edited without an active `.context/<feature-slug>/PLAN.md`, warns: "Consider /build for tracked changes." Dismissible via `.context/.no-nudge`. |
+| **context-monitor** | `context-monitor.js` | PostToolUse on * | Warns at 60% context usage (suggest subagents) and 80% (suggest finishing current task). Silent if runtime doesn't expose context metrics. |
+| **session-start** | `session-start.sh` | Session start | Shows unchecked features from `.ystack/progress/` and any in-progress plans in `.context/`. |
+
+### Progress Integrity Hooks
+
+| Hook | File | Trigger | What it does |
+|------|------|---------|-------------|
+| **progress-before-ship** | `progress-before-ship.js` | PreToolUse on Bash (git push / gh pr create) | Warns if the branch has code changes but no `.ystack/progress/` updates. Catches `/go` forgetting to check the box. |
+| **docs-match-progress** | `docs-match-progress.js` | PostToolUse on Edit/Write (doc files) | After editing a doc file, checks that `[x]` items in the module's progress file don't still have `<!-- ystack:stub -->` in docs. Catches incomplete doc updates. |
+| **no-undocumented-check** | `no-undocumented-check.js` | PreToolUse on Edit (progress files) | When checking a box `[x]` in a progress file, warns if the linked doc section still has `<!-- ystack:stub -->`. Reminds you to run `/docs` before `/pr`. |
 
-These ship with ystack out of the box.
+---
 
-### Workflow Rules
+## Design Spec — Not Yet Implemented
+
+The rules below are enforced by the skill prompts themselves (the SKILL.md instructions tell the agent what to check). They are not separate hook implementations. A future version of ystack may extract these into standalone hooks for harder enforcement.
+
+### Workflow Rules (prompt-enforced)
 
 | 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. |
+| `decisions-before-execute` | Block | During `/go` | Does `.context/<feature-slug>/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. |
+| `no-scope-reduction` | Block | During `/build` | Does the plan cover ALL locked decisions from DECISIONS.md? Catches silent simplification. |
 
-### Verification Rules
+### Verification Rules (prompt-enforced)
 
 | 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
+### Documentation Rules (prompt-enforced)
 
 | 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`. |
+| `module-registered` | Warn | During `/build` | Is the target module in `.ystack/config.json`? Catches work outside any module's scope. |
 | `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.
@@ -100,17 +114,15 @@ 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`:
+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",
@@ -137,53 +149,6 @@ Rules evolve with the project:
 }
 ```
 
-## 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 |
@@ -193,6 +158,6 @@ Rules do NOT:
 | **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` |
+| **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

@@ -28,7 +28,7 @@ You write it once. It serves all four purposes. There is no separate "planning d
 
 ```
 Docs        →  What the system IS (final state)
-Beads       →  What's been done, what's left (development state)
+Progress    →  What's been done, what's left (development state)
 Code        →  The actual implementation
 ```
 
@@ -36,9 +36,9 @@ 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.
+**Progress files** track the journey. They record which features are implemented (checked), which are not yet built (unchecked), and which are blocked (via `depends-on:` annotations). They hold the decisions made during implementation and the notes that let an agent resume work after a context reset. Progress files are the development state — committed to git, branching and merging with the code they track.
 
-**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.
+**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 `.ystack/progress/`. The code just works.
 
 ## Why Human-Readable Markdown
 
@@ -62,7 +62,7 @@ This matters because:
 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.
+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 the progress files." From that map, the agent reads what it needs, when it needs it.
 
 ## Connected Documentation
 
@@ -91,21 +91,21 @@ The module registry bridges three worlds:
       "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.
+Progress is tracked by convention in `.ystack/progress/<module-key>.md` — one file per module, with feature checklists, decisions, and notes.
 
-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 tracks **modules only**. Sub-modules are tracked by the docs site (sub-pages within a module). Features are tracked in progress files (checklist items in the module's progress file). Each layer has its own hierarchy — the registry connects the top level.
 
-The registry is small, stable, and rarely changes. It's the index — the docs, code, and beads are the content.
+When a feature is checked off in a progress file, 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 progress files are the content.
 
 ## Documentation Reflects Only Completed Work
 
@@ -119,7 +119,7 @@ This means:
 - 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.
+Progress files track what's planned and in progress. That's their role. Docs track what's done. The boundary is clean.
 
 ## Why This Works for Teams
 

package/README.md

@@ -1,81 +1,134 @@
 # ystack
 
-An agent harness for doc-driven development — built on top of [Beads](https://github.com/gastownhall/beads).
+```
+                 _             _
+  _   _ ___| |_ __ _  ___| | __
+ | | | / __| __/ _` |/ __| |/ /
+ | |_| \__ \ || (_| | (__|   <
+  \__, |___/\__\__,_|\___|_|\_\
+  |___/
+```
+
+[![npm version](https://img.shields.io/npm/v/ystack)](https://www.npmjs.com/package/ystack)
+[![license](https://img.shields.io/npm/l/ystack)](./LICENSE)
+
+**An agent harness for doc-driven development** — with git-native progress tracking.
 
 > **Status:** Early release (v0.1) — Claude Code only. Multi-runtime support is planned.
 
+```bash
+# Interactive setup guide
+npx ystack
+
+# New project with opinionated defaults
+npx ystack create my-app
+
+# Add to an existing project
+cd your-project && npx ystack init
+```
+
+---
+
 ## Why
 
-AI coding agents are capable but unstructured. Without guardrails, they:
+AI coding agents are capable but unstructured. Without guardrails:
+
+```
+  Without ystack                       With ystack
+  ──────────────                       ──────────────
+
+  "Build auth"                         "Build auth"
+       │                                    │
+       ▼                                    ▼
+  ┌────────────┐                       ┌────────────┐
+  │ Hallucinate│                       │ Read spec  │
+  │ a design   │                       │ first      │
+  └─────┬──────┘                       └─────┬──────┘
+        ▼                                    ▼
+  ┌────────────┐                       ┌────────────┐
+  │ Code it all│                       │ Plan tasks │
+  │ at once    │                       │ you confirm│
+  └─────┬──────┘                       └─────┬──────┘
+        ▼                                    ▼
+  ┌────────────┐                       ┌────────────┐
+  │ "Done!"    │                       │ Execute +  │
+  │ (is it?)   │                       │ verify     │
+  └─────┬──────┘                       └─────┬──────┘
+        ▼                                    ▼
+  ┌────────────┐                       ┌────────────┐
+  │ Docs? What │                       │ Update     │
+  │ docs?      │                       │ docs       │
+  └────────────┘                       └────────────┘
+```
 
-- **Hallucinate architecture** — invent module boundaries that don't exist
-- **Silently simplify** — deliver a "v1" of what you asked for instead of the real thing
-- **Lose context** — forget decisions from 20 minutes ago as the context window fills
-- **Skip verification** — mark tasks done without checking the code actually works
-- **Ignore docs** — write code that drifts from the documented design, or never update docs at all
+See [PHILOSOPHY.md](./PHILOSOPHY.md) for the full design rationale.
 
-ystack fixes this. It makes agents read the spec before coding, plan before executing, verify against success criteria, and update docs when done. See [PHILOSOPHY.md](./PHILOSOPHY.md) for the full design rationale.
+---
 
 ## How It Works
 
 Three layers, connected by a module registry:
 
 ```
-  Docs (MDX)          Beads (bd)           Code
-  What it IS    ◄───  What's done /  ───►  The actual
-  Final specs         what's left          implementation
-       ▲                   ▲                    ▲
-       └───────────────────┴────────────────────┘
-                    Module Registry
-                  (ystack.config.json)
+  ┌──────────────────────────────────────────────────────────┐
+  │                    .ystack/config.json                    │
+  │                     (Module Registry)                     │
+  ├──────────────────┬──────────────────┬────────────────────┤
+  │                  │                  │                    │
+  │   Docs (MDX)     │   Progress       │   Code             │
+  │   ━━━━━━━━━━     │   (.ystack/)     │   ━━━━             │
+  │   What it IS     │   ━━━━━━━━━━     │   The actual       │
+  │   Final specs    │   What's DONE    │   implementation   │
+  │   Design truth   │   What's LEFT    │   Lives here       │
+  │                  │   State layer    │                    │
+  │   agents read <──┼── tracks ───────>┼── agents write     │
+  │                  │                  │                    │
+  └──────────────────┴──────────────────┴────────────────────┘
 ```
 
-| Layer | Role |
-|-------|------|
-| **Docs** | The spec agents read, the reference your team reads, the contract between modules. Written once, serves all three. |
-| **Beads** | Development state machine. What's built, in progress, or blocked. Persistent memory that survives context resets. |
-| **Code** | The implementation. Architecture lives in docs, progress lives in Beads. |
-
-Each module in `ystack.config.json` maps a doc page, code scope (glob patterns), and a Beads epic:
+Each module maps a doc page and code scope:
 
 ```json
 {
   "modules": {
     "payments": {
       "doc": "shared/payments",
-      "scope": ["packages/payments/**", "apps/api/src/routes/payments.*"],
-      "epic": "bd-a1b2"
+      "scope": ["packages/payments/**", "apps/api/src/routes/payments.*"]
     }
   }
 }
 ```
 
-## Commands
+---
 
-### Setup
+## The Workflow
 
-| Command | What it does |
-|---------|-------------|
-| `/scaffold` | Takes a big plan, splits it into module doc stubs + interaction diagrams + epic beads |
-| `/import` | Scans an existing repo, generates module registry, flags doc gaps |
+```
+  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
+  │/scaffold │───>│  /build  │───>│   /go    │───>│ /review  │───>│  /docs   │───>│   /pr    │
+  │ or       │    │          │    │          │    │          │    │          │    │          │
+  │/import   │    │ Plan &   │    │ Execute  │    │ Verify   │    │ Update   │    │ Ship     │
+  │          │    │ confirm  │    │ tasks w/ │    │ against  │    │ docs for │    │ it       │
+  │ Scan or  │    │ with     │    │ fresh    │    │ success  │    │completed │    │          │
+  │ scaffold │    │ user     │    │subagents │    │ criteria │    │ work     │    │          │
+  └──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘
+```
 
-### Build cycle
+### Commands
 
 | Command | What it does |
 |---------|-------------|
+| `/scaffold` | Takes a big plan, splits into module doc stubs + diagrams + progress files |
+| `/import` | Scans existing repo, generates module registry, flags doc gaps |
 | `/build <feature>` | Reads docs + code, surfaces assumptions, creates a plan. You confirm. |
-| `/go` | Executes the plan — fresh subagent per task, atomic commits. |
-| `/review` | Code review + goal-backward verification against success criteria. |
-| `/docs` | Updates documentation for completed work (only completed, never planned). |
-| `/pr` | Verify, docs check, create PR. |
-| `/address-review` | Fetch PR review comments, triage by priority, address approved fixes. |
+| `/go` | Executes the plan — fresh subagent per task, atomic commits |
+| `/quick` | Fast path for bug fixes, chores, small changes — skip planning and progress |
+| `/review` | Code review + goal-backward verification against success criteria |
+| `/docs` | Updates documentation for completed work (only completed, never planned) |
+| `/pr` | Verify, docs check, create PR |
+| `/address-review` | Fetch PR review comments, triage by priority, address approved fixes |
 
-### The flow
-
-```
-New project:       big plan → /scaffold → /build → /go → /review → /docs → /pr
-Existing project:  repo → /import → /build → /go → /review → /docs → /pr
-```
+---
 
 ## Getting Started
 
@@ -96,7 +149,14 @@ See [INSTALL.md](./INSTALL.md) for full setup options, prerequisites, and config
 - [INSTALL.md](./INSTALL.md) — Installation and default stack
 - [LINTING.md](./LINTING.md) — Agent linting rules
 - [RUNTIMES.md](./RUNTIMES.md) — Multi-runtime support
-- [PLAN.md](./PLAN.md) — Roadmap and command specs
+
+## Contributing
+
+Issues and PRs welcome. Please open an issue before starting large changes.
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for release history.
 
 ## License
 

package/RUNTIMES.md

@@ -58,10 +58,10 @@ ystack/
 ### Core (agent-agnostic)
 
 The prompts in `core/prompts/` are the actual skill logic. They reference:
-- `ystack.config.json` for the module registry
-- `bd` CLI for Beads operations
+- `.ystack/config.json` for the module registry
+- `.ystack/progress/` for development state
 - Doc page paths (resolved from the registry)
-- `.context/<bead-id>/` for temporary state
+- `.context/<feature-slug>/` for temporary state
 
 These are pure markdown instructions that any LLM can follow. They don't use Claude-specific features, tool names, or XML tags.
 
@@ -105,7 +105,7 @@ Not all runtimes can do everything. ystack degrades gracefully:
 | **Runtimes** | Claude Code, Gemini CLI | Codex, Cursor | Copilot, Windsurf |
 | **Subagents** | Yes — fresh context per task | No — inline execution | No |
 | **Hooks** | Yes — pre/post tool use | No — rules embedded in prompts | No |
-| **Beads** | Full (`bd` CLI) | Full (`bd` CLI) | Full (`bd` CLI) |
+| **Progress files** | Git-native markdown | Git-native markdown | Git-native markdown |
 | **Docs reading** | Selective (agent navigates) | Selective | Selective |
 | **Plan-checker** | Separate agent validates | Self-check in same context | Self-check |
 | **Parallel execution** | Yes (wave-based) | Sequential | Sequential |
@@ -121,7 +121,7 @@ Claude Code and Gemini CLI support subagents and hooks. They get the full experi
 
 ### Tier 2: Inline Execution
 
-Codex and Cursor can run `bd` commands and read files, but have no subagent support. The harness adapts:
+Codex and Cursor can read files, but have no subagent support. The harness adapts:
 - `/go` executes tasks sequentially in the same context
 - Plan-checker runs as a self-review step (not a separate agent)
 - Lint rules are embedded in the prompt ("before editing, verify you've read the spec")
@@ -134,22 +134,22 @@ This is still valuable. The workflow (build → go → review → docs → pr) w
 Copilot and Windsurf have minimal configuration. They get the workflow as natural language instructions:
 - No slash commands — the instructions describe the process to follow
 - The agent is told: "When asked to build a feature, first read the module's doc page..."
-- Beads still works (any agent with shell access can use `bd`)
+- Progress files are just markdown — any agent can read and write them
 - Verification is self-check only
 
-Even at this tier, having Beads + docs + module registry is a significant upgrade over nothing.
+Even at this tier, having progress files + docs + module registry is a significant upgrade over nothing.
 
 ## What Stays Universal
 
 Regardless of runtime, every agent gets:
 
-1. **Beads** — any agent with shell access can run `bd ready`, `bd create`, `bd close`. The persistent memory layer works everywhere.
+1. **Progress files** — any agent can read and write markdown. The progress tracking layer (`.ystack/progress/`) is just files in git.
 
 2. **Docs** — every agent can read markdown files. The documentation-as-spec pattern is runtime-agnostic.
 
-3. **Module registry** — `ystack.config.json` is JSON. Any agent can parse it to find the right doc page and code scope.
+3. **Module registry** — `.ystack/config.json` is JSON. Any agent can parse it to find the right doc page and code scope.
 
-4. **`.context/<bead-id>/`** — PLAN.md and DECISIONS.md are markdown files. Any agent can read and write them.
+4. **`.context/<feature-slug>/`** — PLAN.md and DECISIONS.md are markdown files. Any agent can read and write them.
 
 5. **The workflow** — build → go → review → docs → pr is a process, not a tool feature. It works in any agent that can follow multi-step instructions.