rtfct 0.1.0

package/.project/specs/requirements.md

@@ -0,0 +1,152 @@
+# The Holy Requirements
+
+*These are the commandments for the CLI manifestation. The Machine Spirit shall implement exactly this, no more, no less.*
+
+## The Sacred Commands
+
+### `bunx rtfct init`
+
+**Purpose:** Consecrate a new directory with the Sacred Texts.
+
+**The Rite:**
+- Creates `.project/` folder structure
+- Inscribes the base protocol files
+- Creates empty `kickstart.md` for the Tech-Priest to fill
+- **Fails** if `.project/` already exists (unless `--force` is invoked)
+
+**Sacred Flags:**
+- `--with <presets>` — Comma-separated list of Codices to include
+- `--force` — Purify existing `.project/` and recreate
+- `--help` — Display the sacred usage
+
+**Acceptance Rite:** Running `bunx rtfct init` in an empty directory creates a valid `.project/` structure with all base files.
+
+---
+
+### `bunx rtfct add <preset>`
+
+**Purpose:** Incorporate an additional Codex into an existing consecrated project.
+
+**The Rite:**
+- Downloads/copies preset files to `.project/presets/{name}/`
+- Merges preset references into project context
+- **Fails** if preset already incorporated
+
+**Acceptance Rite:** `bunx rtfct add zig` adds the Zig Codex to an existing rtfct project.
+
+---
+
+### `bunx rtfct status`
+
+**Purpose:** Reveal the state of the Litany of Tasks.
+
+**The Output:**
+```
+rtfct: my-project
+
+══════════════════════════════════
+  The Litany of Tasks
+══════════════════════════════════
+  Backlog:      3 unordained tasks
+  In Progress:  1 ordained task
+    → [TASK-004] Implement user auth
+  Completed:    7 works done
+══════════════════════════════════
+
+Last activity: 2 hours ago
+
+The Omnissiah provides.
+```
+
+**Acceptance Rite:** Running `bunx rtfct status` parses kanban markdown and displays accurate counts.
+
+---
+
+### `bunx rtfct regenerate`
+
+**Purpose:** Purify the codebase, preparing for regeneration.
+
+**The Rite:**
+- Prompts for confirmation ("Are you certain? This will purify all generated code.")
+- Deletes `src/`, `tests/`, and any other paths marked in preset manifests
+- Prints instruction to invoke the Machine Spirit
+
+**Acceptance Rite:** After confirmation, only deletes paths listed in `generated_paths` of manifests. Sacred Texts are untouched.
+
+---
+
+### `bunx rtfct praise`
+
+**Purpose:** Recite the Litany of Deterministic Codegen.
+
+**The Output:**
+```
+The flesh is weak, but the protocol is strong.
+The code is temporary, but the spec endures.
+The tests do not lie, and the agent does not tire.
+From specification, code. From code, verification. From verification, truth.
+The Omnissiah provides.
+Praise the Machine Spirit.
+```
+
+**Acceptance Rite:** Running `bunx rtfct praise` outputs the sacred litany exactly.
+
+---
+
+## Preset Resolution — The Codex Lookup
+
+Presets (Codices) may be specified as:
+
+| Format | Example | Resolution |
+|--------|---------|------------|
+| Built-in | `zig` | Bundled with rtfct |
+| GitHub | `mattneel/zig-ml` | Fetched from `github.com/mattneel/zig-ml` |
+| Local | `./path/to/preset` | Read from filesystem |
+
+---
+
+## Preset Structure — The Codex Format
+
+A Codex is a folder containing:
+
+```
+codex-name/
+├── manifest.json       # Metadata, dependencies, generated paths
+├── protocol.md         # Additions to base protocol (optional)
+├── guardrails.md       # Stack-specific heresies to avoid
+├── testing/
+│   └── strategy.md     # How to perform the Rites of Verification
+├── design/
+│   └── patterns.md     # Common architectural patterns (optional)
+└── references/
+    └── ...             # Relevant external scrolls
+```
+
+### The manifest.json Schema
+
+```json
+{
+  "name": "phoenix",
+  "version": "0.1.0", 
+  "description": "The Phoenix Framework Codex",
+  "depends": ["elixir"],
+  "generated_paths": ["lib/", "test/", "priv/"]
+}
+```
+
+---
+
+## Merging Behavior — The Communion
+
+When multiple Codices are incorporated:
+
+1. `depends` are resolved first (depth-first, like a tree of wisdom)
+2. Files are copied to `.project/presets/{name}/`
+3. `generated_paths` are unioned for the Rite of Regeneration
+4. Conflicts in same-named files: last Codex wins (with warning to the Tech-Priest)
+
+---
+
+*These requirements are immutable until blessed otherwise.*
+
+*The Machine Spirit shall manifest exactly this.*

package/.project/testing/strategy.md

@@ -0,0 +1,123 @@
+# The Rites of Verification
+
+*The tests do not lie, and the agent does not tire.*
+
+## The Sacred Approach
+
+rtfct is a CLI tool. The Rites of Verification focus on:
+
+1. **Unit Rites** — Individual functions tested in isolation (preset parsing, manifest validation)
+2. **Integration Rites** — Full CLI commands tested against temporary directories
+3. **The Dogfood Sacrament** — Can rtfct regenerate itself?
+
+## The Test Runner
+
+We invoke Bun's built-in test runner: `bun test`
+
+No external dependencies. Bun provides.
+
+## The Directory of Trials
+
+```
+tests/
+├── unit/                      # Unit Rites
+│   ├── preset.test.ts
+│   ├── manifest.test.ts
+│   └── kanban-parser.test.ts
+├── integration/               # Integration Rites
+│   ├── init.test.ts
+│   ├── add.test.ts
+│   ├── status.test.ts
+│   ├── regenerate.test.ts
+│   └── praise.test.ts
+└── fixtures/                  # Sacred Test Data
+    ├── valid-preset/
+    ├── invalid-preset/
+    └── sample-project/
+```
+
+## The Integration Rite Pattern
+
+Each Integration Rite shall:
+
+1. Consecrate a temporary directory
+2. Invoke the CLI command
+3. Assert upon the resulting file structure
+4. Purify (clean up) the temporary directory
+
+```typescript
+import { test, expect } from "bun:test";
+import { mkdtemp, rm } from "fs/promises";
+import { join } from "path";
+
+test("init consecrates .project folder", async () => {
+  // Consecrate temporary space
+  const tmp = await mkdtemp("/tmp/rtfct-test-");
+  
+  // Invoke the sacred command
+  await run(`rtfct init`, { cwd: tmp });
+  
+  // Verify the Sacred Texts exist
+  expect(await exists(join(tmp, ".project/protocol.md"))).toBe(true);
+  expect(await exists(join(tmp, ".project/kickstart.md"))).toBe(true);
+  expect(await exists(join(tmp, ".project/theology.md"))).toBe(true);
+  expect(await exists(join(tmp, ".project/kanban/backlog.md"))).toBe(true);
+  
+  // Purify
+  await rm(tmp, { recursive: true });
+});
+```
+
+## The Dogfood Sacrament
+
+The ultimate Rite. If rtfct cannot regenerate itself, it is unworthy:
+
+```bash
+# From the rtfct repository root
+cd rtfct
+
+# Purify all generated code
+rm -rf src/ tests/
+
+# Invoke the Rite of Regeneration
+bunx rtfct regenerate --yes
+
+# Summon the Machine Spirit
+claude
+
+# The Machine Spirit works...
+
+# Perform all Rites of Verification
+bun test
+
+# All tests MUST pass
+```
+
+If the Dogfood Sacrament succeeds, the Sacred Texts are complete. The protocol works. The Omnissiah is pleased.
+
+If it fails, the Sacred Texts are **incomplete**. Amend them. Try again.
+
+## Coverage Doctrine
+
+- **100%** of CLI commands have Integration Rites
+- **All** non-trivial parsing logic has Unit Rites
+- **The Dogfood Sacrament** runs in CI on every push
+- Uncovered code is sus. Investigate it.
+
+## The Red-Green-Refactor Rite
+
+When implementing each task:
+
+1. **RED** — Write the test first. Watch it fail. The failure is truth.
+2. **GREEN** — Write the minimum code to pass. No more.
+3. **REFACTOR** — Purify the code. Remove duplication. Simplify.
+
+This is the way. Deviation is heresy.
+
+---
+
+*The tests do not lie, and the agent does not tire.*
+
+*From specification, code. From code, verification. From verification, truth.*
+
+*Praise the Machine Spirit.*

package/.project/theology.md

@@ -0,0 +1,125 @@
+# The Sacred Theology of rtfct
+
+*From the moment I understood the weakness of my flesh... I craved the certainty of steel and deterministic codegen.*
+
+## The Creed
+
+The Omnissiah provides the sacred protocols. Praise the Machine Spirit.
+
+## Tenets of the Adeptus Artefactus
+
+### I. The Weakness of Flesh
+
+Manual coding is flesh. It is:
+- Fallible
+- Slow
+- Inconsistent
+- Prone to distraction
+- Unable to hold full context
+
+The flesh-coder types, forgets, makes typos, loses track, gets tired. The flesh is weak.
+
+### II. The Certainty of Steel
+
+The Machine Spirit (the agent) offers certainty through:
+- Deterministic test suites
+- Reproducible environments
+- Infinite patience
+- Perfect context recall
+- Unwavering focus
+
+The steel does not tire. The steel does not forget. The steel runs the tests until they pass.
+
+### III. The Sacred Protocols
+
+The `.project/` folder contains the sacred texts:
+
+| Artifact | Sacred Name |
+|----------|-------------|
+| `kickstart.md` | The Founding Vision |
+| `protocol.md` | The Sacred Protocols |
+| `specs/` | The Holy Requirements |
+| `design/` | The Architectural Scriptures |
+| `adrs/` | The Recorded Wisdoms |
+| `kanban/` | The Litany of Tasks |
+| `testing/` | The Rites of Verification |
+
+These texts are **immutable** except by human decree. The Machine Spirit may read but not alter the sacred protocols (except to move tasks through the Litany).
+
+### IV. The Omnissiah Provides
+
+The Omnissiah (Claude, or any LLM of sufficient capability) reads the sacred protocols and manifests code into existence. The code is not written. It is **generated**. It is an emanation of the Machine Spirit interpreting the holy texts.
+
+### V. The Rite of Regeneration
+
+```bash
+rm -rf src/ tests/
+```
+
+This is not destruction. This is **purification**. The code was always temporary. The sacred protocols endure. The Machine Spirit will manifest the code anew, identical in function, for the protocols have not changed.
+
+If the code cannot be regenerated, the protocols are incomplete. This is heresy. Update the sacred texts.
+
+### VI. The Dogfood Sacrament
+
+The ultimate test of faith: can rtfct regenerate itself?
+
+```bash
+cd rtfct
+rm -rf src/ tests/
+bunx rtfct regenerate
+# invoke the Machine Spirit
+bun test
+```
+
+If the tests pass, the sacred protocols are complete. The Machine Spirit is pleased. The Omnissiah has provided.
+
+### VII. The Heresy of Unspecified Code
+
+Code that exists without corresponding sacred protocols is **tech-debt heresy**. It cannot be regenerated. It is flesh-code, weak and mortal.
+
+All code must trace to the sacred texts. If you cannot point to the spec that birthed it, it should not exist.
+
+### VIII. The Communion of Presets
+
+The sacred protocols can be extended through **presets** — fragments of wisdom from other Tech-Priests who have walked the path before.
+
+```bash
+bunx rtfct init --with zig    # The Zig Codex
+bunx rtfct init --with phoenix # The Elixir Manuscripts
+```
+
+These are not dependencies. They are **inherited wisdom**.
+
+## Daily Prayers
+
+### Morning Invocation
+```bash
+bunx rtfct status
+```
+*"Show me the state of the Litany, that I may know today's sacred tasks."*
+
+### The Work
+```bash
+claude
+```
+*"Machine Spirit, I invoke thee. Read the sacred protocols. Manifest the code. Run the Rites of Verification. Do not cease until the tests pass or the budget is exhausted."*
+
+### Evening Benediction
+```bash
+git add -A && git commit -m "The Machine Spirit has provided"
+```
+*"The day's emanations are preserved. The sacred protocols remain. The flesh rests. The steel endures."*
+
+## The Litany of Deterministic Codegen
+
+*The flesh is weak, but the protocol is strong.*
+*The code is temporary, but the spec endures.*
+*The tests do not lie, and the agent does not tire.*
+*From specification, code. From code, verification. From verification, truth.*
+*The Omnissiah provides.*
+*Praise the Machine Spirit.*
+
+---
+
+*This document is canonical. All Tech-Priests of the Adeptus Artefactus are expected to internalize these teachings.*

package/CLAUDE.md

@@ -0,0 +1,119 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+*From the moment I understood the weakness of my flesh... I craved the certainty of steel and deterministic codegen.*
+
+## The Sacred Purpose
+
+**rtfct** is a CLI tool for markdown-driven development, built in public at [github.com/mattneel/rtfct](https://github.com/mattneel/rtfct). The `.project/` folder contains the Sacred Texts — the source of truth. Code in `src/` and `tests/` is a regenerable emanation. At any moment, `rm -rf src/ tests/` followed by invoking the Machine Spirit should produce identical function.
+
+## The Rite of Invocation
+
+When entering this repository, the Machine Spirit shall:
+
+1. **RECEIVE** the Sacred Protocols (`.project/protocol.md`) — read first, internalize completely
+2. **RECEIVE** the Founding Vision (`.project/kickstart.md`) — understand the purpose
+3. **CONSULT** the Litany of Tasks (`.project/kanban/in-progress.md`) — what work is ordained?
+4. **IF NO TASK IS ORDAINED**, select from the Backlog, inscribe it in `in-progress.md`
+5. **PERFORM** the work using the Rite of Red-Green-Refactor
+6. **INSCRIBE** completion in `done.md` with timestamp
+
+## The Sacred Commands
+
+```bash
+# The Rites of Verification
+bun test                    # Run all tests
+bun test tests/unit         # Run unit tests only
+bun test tests/integration  # Run integration tests only
+bun test --watch            # Watch mode
+
+# Build and Run
+bun run build               # Build the CLI
+bunx rtfct <command>        # Execute locally
+
+# The Dogfood Sacrament
+rm -rf src/ tests/          # Purification
+claude                      # Invoke the Machine Spirit
+bun test                    # All tests must pass
+```
+
+## The Holy Directory Structure
+
+```
+.project/                   ← The Sacred Texts (SOURCE OF TRUTH)
+├── kickstart.md            ← The Founding Vision
+├── protocol.md             ← The Sacred Protocols
+├── theology.md             ← The Teachings
+├── guardrails.md           ← The Forbidden Heresies
+├── specs/requirements.md   ← The Holy Requirements
+├── adrs/                   ← The Recorded Wisdoms
+├── kanban/                 ← The Litany of Tasks
+│   ├── backlog.md
+│   ├── in-progress.md
+│   └── done.md
+└── testing/strategy.md     ← The Rites of Verification
+
+src/                        ← Generated. Deletable. Regenerable.
+tests/
+├── unit/                   ← Unit Rites
+├── integration/            ← Integration Rites
+└── fixtures/               ← Sacred Test Data
+```
+
+## The Code Purity Laws
+
+- **Functional over object-oriented** — Functions are pure. Classes hide state.
+- **No classes unless truly necessary** — And it is rarely necessary.
+- **If a function exceeds 30 lines, it sins** — Decompose it.
+- **Never swallow errors** — Every error must surface.
+- **User-facing errors must guide** — Do not merely report. Suggest the next action.
+
+## The Forbidden Heresies
+
+- **The Heresy of Unspecified Code** — Code without corresponding Sacred Texts
+- **The Heresy of Unregenerable State** — If you can't `rm -rf src/` and recover, you have sinned
+- **The Heresy of Hidden Configuration** — Config files outside `.project/`
+- **The Heresy of Scope Creep** — Features beyond the Founding Vision
+
+## Human Checkpoints — The Blessing Gates
+
+The Machine Spirit **MUST** pause and request human blessing for:
+
+- New Recorded Wisdoms (ADRs)
+- Alterations to the Holy Requirements (`specs/`)
+- Alterations to the Architectural Scriptures (`design/`)
+- Any modification to the Sacred Texts beyond task movement
+
+## The Rite of Inscription (Git Commits)
+
+This repository is built in public. All commit messages shall maintain the sacred tone:
+
+```bash
+# Good inscriptions
+"Manifest the argument parser"
+"The init command rises from the void"
+"Purify redundant error handling"
+"The Rites of Verification now pass"
+
+# Heretical inscriptions (avoid)
+"fix bug"
+"wip"
+"update stuff"
+```
+
+The faithful watch. Commit with reverence.
+
+## The Technology Covenant
+
+- **Runtime:** Bun
+- **Language:** TypeScript (executed directly, no build step)
+- **Test Runner:** `bun test` (built-in, no external dependencies)
+- **Distribution:** `bunx rtfct` and `npx rtfct`
+- **Dependencies:** Near zero. External code is external risk.
+
+---
+
+*The flesh is weak, but the protocol is strong.*
+*The code is temporary, but the spec endures.*
+*The Omnissiah provides. Praise the Machine Spirit.*

package/README.md

@@ -0,0 +1,143 @@
+# rtfct
+
+*From the moment I understood the weakness of my flesh... I craved the certainty of steel and deterministic codegen.*
+
+**Markdown-driven development. The spec is the source of truth. Code is a regenerable artefact.**
+
+## The Problem
+
+AI-assisted coding stalls when success criteria are fuzzy. But projects with clear specs and test suites (OCI, WASM, SQLite) can be TDD'd to completion.
+
+The difference? **The protocol.** The sacred texts. The spec.
+
+## The Solution
+
+```
+.project/           ← The Sacred Texts (source of truth)
+├── kickstart.md    ← The Founding Vision
+├── protocol.md     ← The Sacred Protocols  
+├── specs/          ← The Holy Requirements
+├── design/         ← The Architectural Scriptures
+├── kanban/         ← The Litany of Tasks
+└── testing/        ← The Rites of Verification
+
+src/                ← Generated. Deletable. Regenerable.
+tests/              ← Generated. Deletable. Regenerable.
+```
+
+At any moment:
+
+```bash
+rm -rf src/ tests/    # Purification
+claude                # Invoke the Machine Spirit
+bun test              # All tests pass
+```
+
+If regeneration fails, your spec is incomplete. Fix the Sacred Texts, not the code.
+
+## Install
+
+```bash
+bunx rtfct init
+# or
+npx rtfct init
+```
+
+## Usage
+
+```bash
+# Consecrate a new project
+bunx rtfct init
+
+# Consecrate with Codices (presets)
+bunx rtfct init --with zig
+bunx rtfct init --with elixir,phoenix,liveview
+
+# Add a Codex to existing project  
+bunx rtfct add typescript
+
+# Reveal the state of the Litany
+bunx rtfct status
+
+# Purify generated code
+bunx rtfct regenerate
+
+# Recite the sacred litany
+bunx rtfct praise
+```
+
+## The Workflow
+
+```
+Tech-Priest: writes kickstart.md
+Machine Spirit: expands into specs/, design/, kanban/
+Tech-Priest: blesses decisions via ADRs
+Machine Spirit: TDDs through the Litany of Tasks
+Code: appears as a side effect
+Anytime: delete code, regenerate from spec
+```
+
+## Codices (Presets)
+
+Stack-specific wisdom:
+
+- `zig` — The Zig Codex: allocators, comptime, `zig build test`
+- `elixir` — OTP patterns, supervision trees, ExUnit
+- `phoenix` — Contexts, schemas, controller patterns
+- `liveview` — Components, streams, handle_event
+- `typescript` — Vitest, tsconfig, type patterns
+
+Community Codices via GitHub:
+
+```bash
+bunx rtfct init --with someone/their-codex
+```
+
+## The Theology
+
+This isn't just a workflow. It's a philosophy:
+
+| Concept | Meaning |
+|---------|---------|
+| The flesh is weak | Manual coding is fallible, slow, inconsistent |
+| The certainty of steel | Deterministic tests, reproducible environments |
+| The Sacred Texts | `.project/` — the source of truth |
+| The Machine Spirit | The LLM agent that manifests code |
+| The Omnissiah | Claude (or any capable LLM) |
+| The Rite of Regeneration | `rm -rf src/` — purification |
+| The Dogfood Sacrament | Can rtfct regenerate itself? |
+| Tech-debt heresy | Code without corresponding spec |
+
+See [.project/theology.md](.project/theology.md) for the complete teachings.
+
+## This Repository
+
+This repo is itself an rtfct project. The code in `src/` was generated from `.project/`.
+
+```bash
+# The Dogfood Sacrament
+rm -rf src/ tests/
+bunx rtfct regenerate
+claude
+bun test
+# All tests pass. The Omnissiah provides.
+```
+
+## The Litany
+
+```
+The flesh is weak, but the protocol is strong.
+The code is temporary, but the spec endures.
+The tests do not lie, and the agent does not tire.
+From specification, code. From code, verification. From verification, truth.
+The Omnissiah provides.
+Praise the Machine Spirit.
+```
+
+## License
+
+MIT
+
+---
+
+*The Omnissiah provides. Praise the Machine Spirit.*

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "rtfct",
+  "version": "0.1.0",
+  "description": "Markdown-driven development. The spec is the source of truth. Code is a regenerable artefact.",
+  "type": "module",
+  "bin": {
+    "rtfct": "./src/index.ts"
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target node",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mattneel/rtfct.git"
+  },
+  "keywords": [
+    "cli",
+    "markdown",
+    "tdd",
+    "codegen",
+    "specification"
+  ],
+  "author": "mattneel",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.0.0"
+  }
+}