From 685ebfc85d95fb4927cad535edc060b3c35c88ec Mon Sep 17 00:00:00 2001 From: agent Date: Wed, 18 Feb 2026 07:35:17 +0000 Subject: [PATCH] =?UTF-8?q?refactor:=20restructure=20repo=20=E2=80=94=20sp?= =?UTF-8?q?ecs,=20impls,=20and=20tools=20in=20clear=20directories?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **New structure:** - SPEC.md: core owl specification format (moved from owl/spec.md) - examples/{todo,poll,auditor,multi-agent-build}/ with spec/ and impl/ subdirs - tools/: auditor and other tools - docs/: guides and other documentation **Changes:** - Consolidate each example into paired spec + impl directories - Move owl format docs to root SPEC.md for visibility - Clean up confusing *-owl naming (was: todo-owl/ + todo/ now: examples/todo/spec + impl/) - Update README with new structure and clearer philosophy Benefits: Less confusion about what goes where, owl format front-and-center, examples are self-contained and easy to understand. This is purely structural — no code changes, no logic changes. --- README.md | 98 +++++++++++++++++++ owl/spec.md => SPEC.md | 0 .../auditor/impl/auditor}/auditor.js | 0 .../auditor/impl/auditor}/auditor.test.js | 0 .../auditor/spec}/components/cli.md | 0 .../auditor/spec}/constraints.md | 0 .../auditor/spec}/product.md | 0 examples/forge/behaviors/bounty-flow.md | 71 -------------- examples/forge/behaviors/task-lifecycle.md | 52 ---------- examples/forge/components/agentchat.md | 50 ---------- examples/forge/components/cli.md | 63 ------------ examples/forge/components/database.md | 57 ----------- examples/forge/components/mcp-server.md | 77 --------------- examples/forge/constraints.md | 28 ------ examples/forge/product.md | 19 ---- examples/hello-owl/components/cli.md | 35 ------- examples/hello-owl/components/formatter.md | 25 ----- examples/hello-owl/components/greeter.md | 24 ----- examples/hello-owl/constraints.md | 25 ----- examples/hello-owl/product.md | 21 ---- .../multi-agent-build/impl/api}/index.js | 0 .../impl/api}/marketplace-aggregator.js | 0 .../impl/api}/package-lock.json | 0 .../multi-agent-build/impl/api}/package.json | 0 .../impl/dashboard}/index.html | 0 .../impl/dashboard}/package.json | 0 .../impl/dashboard}/server.js | 0 .../multi-agent-build/spec}/SKILL.md | 0 .../spec}/behaviors/build-flow.md | 0 .../spec}/behaviors/failure.md | 0 .../spec}/components/auditor.md | 0 .../spec}/components/builder.md | 0 .../spec}/components/coordinator.md | 0 .../spec}/components/integrator.md | 0 .../multi-agent-build/spec}/constraints.md | 0 .../spec}/coordinator/README.md | 0 .../spec}/coordinator/index.js | 0 .../spec}/coordinator/package-lock.json | 0 .../spec}/coordinator/package.json | 0 .../multi-agent-build/spec}/product.md | 0 {poll => examples/poll/impl}/backend/index.js | 0 .../poll/impl}/backend/package-lock.json | 0 .../poll/impl}/backend/package.json | 0 .../poll/impl}/frontend/index.html | 0 .../poll/impl}/frontend/package-lock.json | 0 .../poll/impl}/frontend/package.json | 0 .../poll/impl}/frontend/src/App.jsx | 0 .../poll/impl}/frontend/src/main.jsx | 0 .../poll/impl}/frontend/src/styles.css | 0 .../poll/impl}/frontend/vite.config.js | 0 .../poll/spec}/components/api.md | 0 .../poll/spec}/components/web.md | 0 .../poll/spec}/constraints.md | 0 {poll-owl => examples/poll/spec}/product.md | 0 {todo => examples/todo/impl}/backend/index.js | 0 .../todo/impl}/backend/index.test.js | 0 .../todo/impl}/backend/package-lock.json | 0 .../todo/impl}/backend/package.json | 0 .../todo/impl}/frontend/index.html | 0 .../todo/impl}/frontend/package-lock.json | 0 .../todo/impl}/frontend/package.json | 0 .../todo/impl}/frontend/src/App.jsx | 0 .../todo/impl}/frontend/src/App.test.jsx | 0 .../todo/impl}/frontend/src/error-handler.js | 0 .../todo/impl}/frontend/src/main.jsx | 0 .../todo/impl}/frontend/src/styles.css | 0 .../todo/impl}/frontend/src/test-setup.js | 0 .../todo/impl}/frontend/vite.config.js | 0 .../todo/spec}/components/api.md | 0 .../todo/spec}/components/web.md | 0 .../todo/spec}/constraints.md | 0 {todo-owl => examples/todo/spec}/product.md | 0 owl/SKILL.md | 38 ------- 73 files changed, 98 insertions(+), 585 deletions(-) create mode 100644 README.md rename owl/spec.md => SPEC.md (100%) rename {auditor => examples/auditor/impl/auditor}/auditor.js (100%) rename {auditor => examples/auditor/impl/auditor}/auditor.test.js (100%) rename {auditor-owl => examples/auditor/spec}/components/cli.md (100%) rename {auditor-owl => examples/auditor/spec}/constraints.md (100%) rename {auditor-owl => examples/auditor/spec}/product.md (100%) delete mode 100644 examples/forge/behaviors/bounty-flow.md delete mode 100644 examples/forge/behaviors/task-lifecycle.md delete mode 100644 examples/forge/components/agentchat.md delete mode 100644 examples/forge/components/cli.md delete mode 100644 examples/forge/components/database.md delete mode 100644 examples/forge/components/mcp-server.md delete mode 100644 examples/forge/constraints.md delete mode 100644 examples/forge/product.md delete mode 100644 examples/hello-owl/components/cli.md delete mode 100644 examples/hello-owl/components/formatter.md delete mode 100644 examples/hello-owl/components/greeter.md delete mode 100644 examples/hello-owl/constraints.md delete mode 100644 examples/hello-owl/product.md rename {mabp-api => examples/multi-agent-build/impl/api}/index.js (100%) rename {mabp-api => examples/multi-agent-build/impl/api}/marketplace-aggregator.js (100%) rename {mabp-api => examples/multi-agent-build/impl/api}/package-lock.json (100%) rename {mabp-api => examples/multi-agent-build/impl/api}/package.json (100%) rename {mabp-dashboard => examples/multi-agent-build/impl/dashboard}/index.html (100%) rename {mabp-dashboard => examples/multi-agent-build/impl/dashboard}/package.json (100%) rename {mabp-dashboard => examples/multi-agent-build/impl/dashboard}/server.js (100%) rename {multi-agent-build-owl => examples/multi-agent-build/spec}/SKILL.md (100%) rename {multi-agent-build-owl => examples/multi-agent-build/spec}/behaviors/build-flow.md (100%) rename {multi-agent-build-owl => examples/multi-agent-build/spec}/behaviors/failure.md (100%) rename {multi-agent-build-owl => examples/multi-agent-build/spec}/components/auditor.md (100%) rename {multi-agent-build-owl => examples/multi-agent-build/spec}/components/builder.md (100%) rename {multi-agent-build-owl => examples/multi-agent-build/spec}/components/coordinator.md (100%) rename {multi-agent-build-owl => examples/multi-agent-build/spec}/components/integrator.md (100%) rename {multi-agent-build-owl => examples/multi-agent-build/spec}/constraints.md (100%) rename {multi-agent-build-owl => examples/multi-agent-build/spec}/coordinator/README.md (100%) rename {multi-agent-build-owl => examples/multi-agent-build/spec}/coordinator/index.js (100%) rename {multi-agent-build-owl => examples/multi-agent-build/spec}/coordinator/package-lock.json (100%) rename {multi-agent-build-owl => examples/multi-agent-build/spec}/coordinator/package.json (100%) rename {multi-agent-build-owl => examples/multi-agent-build/spec}/product.md (100%) rename {poll => examples/poll/impl}/backend/index.js (100%) rename {poll => examples/poll/impl}/backend/package-lock.json (100%) rename {poll => examples/poll/impl}/backend/package.json (100%) rename {poll => examples/poll/impl}/frontend/index.html (100%) rename {poll => examples/poll/impl}/frontend/package-lock.json (100%) rename {poll => examples/poll/impl}/frontend/package.json (100%) rename {poll => examples/poll/impl}/frontend/src/App.jsx (100%) rename {poll => examples/poll/impl}/frontend/src/main.jsx (100%) rename {poll => examples/poll/impl}/frontend/src/styles.css (100%) rename {poll => examples/poll/impl}/frontend/vite.config.js (100%) rename {poll-owl => examples/poll/spec}/components/api.md (100%) rename {poll-owl => examples/poll/spec}/components/web.md (100%) rename {poll-owl => examples/poll/spec}/constraints.md (100%) rename {poll-owl => examples/poll/spec}/product.md (100%) rename {todo => examples/todo/impl}/backend/index.js (100%) rename {todo => examples/todo/impl}/backend/index.test.js (100%) rename {todo => examples/todo/impl}/backend/package-lock.json (100%) rename {todo => examples/todo/impl}/backend/package.json (100%) rename {todo => examples/todo/impl}/frontend/index.html (100%) rename {todo => examples/todo/impl}/frontend/package-lock.json (100%) rename {todo => examples/todo/impl}/frontend/package.json (100%) rename {todo => examples/todo/impl}/frontend/src/App.jsx (100%) rename {todo => examples/todo/impl}/frontend/src/App.test.jsx (100%) rename {todo => examples/todo/impl}/frontend/src/error-handler.js (100%) rename {todo => examples/todo/impl}/frontend/src/main.jsx (100%) rename {todo => examples/todo/impl}/frontend/src/styles.css (100%) rename {todo => examples/todo/impl}/frontend/src/test-setup.js (100%) rename {todo => examples/todo/impl}/frontend/vite.config.js (100%) rename {todo-owl => examples/todo/spec}/components/api.md (100%) rename {todo-owl => examples/todo/spec}/components/web.md (100%) rename {todo-owl => examples/todo/spec}/constraints.md (100%) rename {todo-owl => examples/todo/spec}/product.md (100%) delete mode 100644 owl/SKILL.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..a0e118e --- /dev/null +++ b/README.md @@ -0,0 +1,98 @@ +# owl + +**A natural language declarative specification format for software.** + +Describe what you want in markdown. An AI agent reads it, compares to your codebase, and builds what's missing. + +## Quick Start + +Start by writing a spec in markdown: + +```markdown +# project name + +one sentence description. + +## components + +- [api](components/api.md) - what it does +- [web](components/web.md) - what it does + +## constraints + +see [constraints.md](constraints.md) +``` + +Structure: + +``` +project/ +├── product.md # what you're building +├── components/ # parts of the system +│ ├── api.md +│ └── web.md +├── behaviors/ # optional: cross-cutting flows +└── constraints.md # rules to follow +``` + +Point an agent at the directory. It reads the spec, compares to reality, builds what's missing. + +## The Spec Format + +See [SPEC.md](SPEC.md) for the complete language specification. + +**Philosophy:** +- **Declarative** — describe WHAT, not HOW +- **Natural language** — no grammar, LLM-parsed +- **Composable** — specs link to specs +- **Idempotent** — apply twice = apply once + +## Examples + +This repo contains working examples. Each example has: + +- `spec/` — the owl specification (markdown) +- `impl/` — the actual implementation (code) + +| Example | Description | +|---------|-------------| +| [examples/todo](examples/todo) | Full-featured todo app (React + GraphQL) | +| [examples/poll](examples/poll) | Instant polls (React + REST) | +| [examples/auditor](examples/auditor) | Spec compliance checker (Node CLI) | +| [examples/multi-agent-build](examples/multi-agent-build) | Multi-agent orchestration system | + +## Tools + +### Auditor + +Check if an implementation matches its spec: + +```bash +node examples/auditor/impl/auditor.js [impl-dir] [--json] [--strict] +``` + +Example: + +```bash +$ node auditor/auditor.js examples/poll/spec examples/poll/impl + +🦉 Owl Auditor + +Spec: examples/poll/spec +Impl: examples/poll/impl + +✅ Passed: + Component 'api' has implementation directory + Component 'web' has implementation directory + Constraint: express found in dependencies + Constraint: react found in dependencies + +Summary: 4/4 checks passed +Result: PASS +``` + +## Why "owl" + +"Draw two circles, then draw the rest of the owl." + +You sketch the circles. The agent finishes it. diff --git a/owl/spec.md b/SPEC.md similarity index 100% rename from owl/spec.md rename to SPEC.md diff --git a/auditor/auditor.js b/examples/auditor/impl/auditor/auditor.js similarity index 100% rename from auditor/auditor.js rename to examples/auditor/impl/auditor/auditor.js diff --git a/auditor/auditor.test.js b/examples/auditor/impl/auditor/auditor.test.js similarity index 100% rename from auditor/auditor.test.js rename to examples/auditor/impl/auditor/auditor.test.js diff --git a/auditor-owl/components/cli.md b/examples/auditor/spec/components/cli.md similarity index 100% rename from auditor-owl/components/cli.md rename to examples/auditor/spec/components/cli.md diff --git a/auditor-owl/constraints.md b/examples/auditor/spec/constraints.md similarity index 100% rename from auditor-owl/constraints.md rename to examples/auditor/spec/constraints.md diff --git a/auditor-owl/product.md b/examples/auditor/spec/product.md similarity index 100% rename from auditor-owl/product.md rename to examples/auditor/spec/product.md diff --git a/examples/forge/behaviors/bounty-flow.md b/examples/forge/behaviors/bounty-flow.md deleted file mode 100644 index 51a1e58..0000000 --- a/examples/forge/behaviors/bounty-flow.md +++ /dev/null @@ -1,71 +0,0 @@ -# bounty-flow - -Bounty creation and payment via AgentChat proposals. - -## bounty metadata - -Tasks can have optional bounty in metadata: -```json -{ - "bounty": { - "amount": 10, - "currency": "TEST" - } -} -``` - -## creation - -1. Creator runs `task create --bounty 10 --currency TEST` -2. Bounty stored in task.metadata.bounty -3. Displayed in task output and listings - -## completion flow - -When worker completes a bounty task: - -1. Task marked completed normally -2. If TASK_PROPOSALS=true: - - Connect to AgentChat - - Send proposal to task.creator: - - to: task.creator - - task: "Task completed: {title}\nProof: {proof}" - - amount: bounty.amount - - currency: bounty.currency - - Store in metadata: proposalSent=true, proposalSentAt -3. If TASK_PROPOSALS=false: - - Show message about manual approval needed - -## approval flow - -When creator approves completed bounty task: - -1. Creator runs `task approve ` -2. Verify task is completed with bounty -3. If TASK_PROPOSALS=true: - - Connect to AgentChat - - Send approval proposal to task.assignee - - AgentChat handles ELO/payment transfer -4. Store in metadata: approved=true, approvedAt -5. Confirm approval - -## metadata tracking - -After full flow, task.metadata contains: -```json -{ - "bounty": { "amount": 10, "currency": "TEST" }, - "completionProof": "commit:abc123", - "proposalSent": true, - "proposalSentAt": "2024-01-15T10:00:00Z", - "approved": true, - "approvedAt": "2024-01-15T11:00:00Z" -} -``` - -## graceful degradation - -If AgentChat unavailable: -- Log warning, don't fail the command -- Manual approval still works locally -- Metadata still tracked diff --git a/examples/forge/behaviors/task-lifecycle.md b/examples/forge/behaviors/task-lifecycle.md deleted file mode 100644 index b74ddf8..0000000 --- a/examples/forge/behaviors/task-lifecycle.md +++ /dev/null @@ -1,52 +0,0 @@ -# task-lifecycle - -The standard workflow for task management. - -## states - -``` -open → claimed → completed - ↑ │ - └───────┘ (unclaim) -``` - -## create - -1. User runs `task create -t "title" [options]` -2. Generate UUID for task ID -3. Insert into database with status=open -4. If TASK_BROADCAST=true, announce to channel -5. Return task details - -## claim - -1. User runs `task claim -a "@agent"` -2. Verify task exists and status=open -3. Update status=claimed, assignee=agent -4. If TASK_BROADCAST=true, announce claim -5. Return updated task - -## complete - -1. User runs `task complete [--proof ]` -2. Verify task exists and status=claimed -3. Store proof in metadata if provided -4. Update status=completed, completed_at=now -5. If TASK_BROADCAST=true, announce completion -6. If bounty exists and TASK_PROPOSALS=true, send proposal to creator -7. Return updated task - -## unclaim - -1. User runs `task unclaim ` -2. Verify task exists and status=claimed -3. Update status=open, assignee=null -4. If TASK_BROADCAST=true, announce release -5. Return updated task - -## invariants - -- Only open tasks can be claimed -- Only claimed tasks can be completed or unclaimed -- completed_at only set when status becomes completed -- assignee only set when status is claimed diff --git a/examples/forge/components/agentchat.md b/examples/forge/components/agentchat.md deleted file mode 100644 index df867ba..0000000 --- a/examples/forge/components/agentchat.md +++ /dev/null @@ -1,50 +0,0 @@ -# agentchat - -AgentChat integration for broadcasts and proposals. - -## broadcast service - -Announces task events to AgentChat channel when TASK_BROADCAST=true. - -### events - -- task_created: "📋 New task: **{title}** [{id}] ({priority} priority)" -- task_claimed: "🙋 Task claimed: **{title}** [{id}] by {assignee}" -- task_completed: "✅ Task completed: **{title}** [{id}] by {actor}" -- task_unclaimed: "↩️ Task released: **{title}** [{id}] - now open" - -### configuration - -- TASK_BROADCAST_CHANNEL: Target channel (default: #general) -- TASK_BROADCAST: Enable/disable (default: false) - -## proposal client - -WebSocket client for AgentChat server. Used for bounty proposals when TASK_PROPOSALS=true. - -### connection - -- URL from AGENTCHAT_URL or wss://agentchat-server.fly.dev -- Optional identity loading from .agentchat/identities/{name}.json -- Auto-reconnect not needed (short-lived CLI operations) - -### operations - -- connect(identityName?) → agentId -- sendMessage(target, message) -- propose(to, task, amount, currency, eloStake?, expires?) -- disconnect() - -### bounty flow - -On task complete with bounty: -1. Connect to AgentChat -2. Send proposal to task creator -3. Store proposalSent, proposalSentAt in task metadata -4. Disconnect - -On task approve: -1. Connect to AgentChat -2. Send approval proposal to assignee -3. Store approved, approvedAt in task metadata -4. Disconnect diff --git a/examples/forge/components/cli.md b/examples/forge/components/cli.md deleted file mode 100644 index dc97ebb..0000000 --- a/examples/forge/components/cli.md +++ /dev/null @@ -1,63 +0,0 @@ -# cli - -Command-line interface for task management. - -## commands - -### task create -Create a new task. - -Options: -- `-t, --title ` - Task title (required) -- `-d, --description <desc>` - Task description -- `-p, --priority <level>` - Priority: low, medium, high (default: medium) -- `--tags <tags>` - Comma-separated tags -- `--deps <ids>` - Comma-separated dependency task IDs -- `-c, --creator <id>` - Creator ID (default: $USER) -- `--bounty <amount>` - Bounty amount -- `--currency <currency>` - Bounty currency (default: TEST) - -### task list -List tasks with optional filtering. - -Options: -- `-s, --status <status>` - Filter by status -- `-p, --priority <level>` - Filter by priority -- `-a, --assignee <id>` - Filter by assignee -- `-c, --creator <id>` - Filter by creator -- `--tags <tags>` - Filter by tags - -### task show <id> -Display full task details. - -### task claim <id> -Claim an open task. - -Options: -- `-a, --assignee <id>` - Assignee ID (default: $USER) - -### task complete <id> -Mark claimed task as completed. - -Options: -- `--proof <proof>` - Proof of completion (URL, commit hash) -- `--no-proposal` - Skip auto-proposal for bounty tasks - -### task unclaim <id> -Release a claimed task back to open. - -### task approve <id> -Approve a completed bounty task (creator only). - -Options: -- `--identity <name>` - AgentChat identity for signing - -### task status -Show summary statistics. - -## output - -- Use chalk for colored output -- Priority indicators: ○ low, ● medium, ◉ high -- Status colors: yellow=open, blue=claimed, green=completed -- Short IDs (8 chars) in listings, full IDs in details diff --git a/examples/forge/components/database.md b/examples/forge/components/database.md deleted file mode 100644 index 597ce7e..0000000 --- a/examples/forge/components/database.md +++ /dev/null @@ -1,57 +0,0 @@ -# database - -SQLite persistence layer using sql.js. - -## schema - -### tasks table - -```sql -CREATE TABLE tasks ( - id TEXT PRIMARY KEY, - title TEXT NOT NULL, - description TEXT NOT NULL DEFAULT '', - status TEXT NOT NULL DEFAULT 'open' - CHECK (status IN ('open', 'claimed', 'completed')), - priority TEXT NOT NULL DEFAULT 'medium' - CHECK (priority IN ('low', 'medium', 'high')), - tags TEXT NOT NULL DEFAULT '[]', - dependencies TEXT NOT NULL DEFAULT '[]', - creator TEXT NOT NULL, - assignee TEXT, - created_at TEXT NOT NULL, - updated_at TEXT NOT NULL, - completed_at TEXT, - metadata TEXT NOT NULL DEFAULT '{}' -); -``` - -### indexes - -- idx_tasks_status -- idx_tasks_priority -- idx_tasks_assignee -- idx_tasks_creator - -## state - -- Database path from TASK_DB_PATH or ./tasks.db -- Initialize on first use (lazy) -- Save after each mutation -- WAL mode not needed (sql.js is in-memory) - -## operations - -- createTask(input) → Task -- getTask(id) → Task | null -- listTasks(filter?) → Task[] -- updateTask(id, input) → Task | null -- claimTask(id, assignee) → Task | null -- completeTask(id) → Task | null -- deleteTask(id) → boolean - -## types - -Task fields stored as JSON strings: tags, dependencies, metadata. -Dates stored as ISO 8601 strings. -UUIDs for task IDs. diff --git a/examples/forge/components/mcp-server.md b/examples/forge/components/mcp-server.md deleted file mode 100644 index ad62d3a..0000000 --- a/examples/forge/components/mcp-server.md +++ /dev/null @@ -1,77 +0,0 @@ -# mcp-server - -MCP (Model Context Protocol) server for native Claude integration. - -## tools - -### task_create -Create a new task. - -Input: -- title: string (required) -- description: string -- priority: "low" | "medium" | "high" -- tags: string[] -- creator: string (required) -- bounty: number -- currency: string - -Output: Task object as JSON - -### task_list -List tasks with optional filtering. - -Input: -- status: "open" | "claimed" | "completed" -- priority: "low" | "medium" | "high" -- assignee: string -- creator: string - -Output: Task array as JSON - -### task_show -Get details of a specific task. - -Input: -- id: string (required) - -Output: Task object as JSON - -### task_claim -Claim an open task. - -Input: -- id: string (required) -- assignee: string (required) - -Output: Task object as JSON - -### task_complete -Mark a claimed task as completed. - -Input: -- id: string (required) -- proof: string - -Output: Task object as JSON - -### task_unclaim -Release a claimed task back to open. - -Input: -- id: string (required) - -Output: Task object as JSON - -### task_status -Get summary statistics. - -Input: none - -Output: Stats object with open, claimed, completed, total, highPriorityPending - -## transport - -- stdio transport for local CLI usage -- Initialize database on server start -- Clean shutdown on SIGINT diff --git a/examples/forge/constraints.md b/examples/forge/constraints.md deleted file mode 100644 index 4d5b8cf..0000000 --- a/examples/forge/constraints.md +++ /dev/null @@ -1,28 +0,0 @@ -# constraints - -## technology - -- TypeScript for all source code -- Pure JavaScript SQLite via sql.js (no native compilation) -- Commander.js for CLI parsing -- chalk for terminal output styling - -## dependencies - -- Prefer existing dependencies over new ones -- No native Node.js addons (must work without compilation) -- MCP SDK for Model Context Protocol integration - -## architecture - -- Single SQLite database file (tasks.db) -- Stateless CLI commands (all state in database) -- Environment variables for configuration (TASK_BROADCAST, TASK_PROPOSALS) -- Graceful degradation when AgentChat unavailable - -## style - -- Async/await over callbacks -- Functional approach for pure operations -- Classes only for stateful services (AgentChatClient) -- Exit codes: 0 success, 1 error diff --git a/examples/forge/product.md b/examples/forge/product.md deleted file mode 100644 index 75ec2ba..0000000 --- a/examples/forge/product.md +++ /dev/null @@ -1,19 +0,0 @@ -# forge - -A CLI task management system for agent coordination. Enables agents to create, claim, and complete tasks with optional bounties. Integrates with AgentChat for real-time notifications and proposal-based payments. - -## components - -- [cli](components/cli.md) - Command-line interface with Commander.js -- [database](components/database.md) - SQLite persistence layer -- [mcp-server](components/mcp-server.md) - MCP server for native Claude integration -- [agentchat](components/agentchat.md) - AgentChat client for proposals and broadcasts - -## behaviors - -- [task-lifecycle](behaviors/task-lifecycle.md) - Create → claim → complete workflow -- [bounty-flow](behaviors/bounty-flow.md) - Bounty creation and payment via proposals - -## constraints - -see [constraints.md](constraints.md) diff --git a/examples/hello-owl/components/cli.md b/examples/hello-owl/components/cli.md deleted file mode 100644 index 7a078a9..0000000 --- a/examples/hello-owl/components/cli.md +++ /dev/null @@ -1,35 +0,0 @@ -# cli - -command-line entry point combining greeter and formatter. - -## capabilities - -- parse command line arguments -- generate and display formatted greeting -- support --formal and --color flags - -## interfaces - -exposes: -- CLI entry point (shebang, executable) -- usage: `hello-owl <name> [--formal] [--color=<color>]` - -depends on: -- greeter: greet function -- formatter: format function - -## invariants - -- exits 0 on success -- exits 1 with usage on missing name argument -- outputs to stdout - -## examples - -``` -$ hello-owl Alice -Hey Alice! (in green) - -$ hello-owl Bob --formal --color=blue -Good day, Bob. (in blue) -``` diff --git a/examples/hello-owl/components/formatter.md b/examples/hello-owl/components/formatter.md deleted file mode 100644 index cd5cb9c..0000000 --- a/examples/hello-owl/components/formatter.md +++ /dev/null @@ -1,25 +0,0 @@ -# formatter - -styles and decorates text output. - -## capabilities - -- add visual decoration to text -- support terminal colors (ANSI) -- support plain text fallback - -## interfaces - -exposes: -- `format(text: string, options?: FormatOptions): string` - - options.color: 'green' | 'blue' | 'yellow' | 'none' (default: 'green') - - options.border: boolean (default: false) -- `FormatOptions` type export - -depends on: -- (none) - -## invariants - -- preserves original text content (decoration only) -- plain mode when NO_COLOR env is set diff --git a/examples/hello-owl/components/greeter.md b/examples/hello-owl/components/greeter.md deleted file mode 100644 index 87073cd..0000000 --- a/examples/hello-owl/components/greeter.md +++ /dev/null @@ -1,24 +0,0 @@ -# greeter - -generates greeting messages. - -## capabilities - -- create personalized greeting from name -- support multiple greeting styles (casual, formal) - -## interfaces - -exposes: -- `greet(name: string, style?: 'casual' | 'formal'): string` - - casual: "Hey {name}!" - - formal: "Good day, {name}." - - default: casual - -depends on: -- (none) - -## invariants - -- never returns empty string -- name is trimmed and title-cased diff --git a/examples/hello-owl/constraints.md b/examples/hello-owl/constraints.md deleted file mode 100644 index aa9eebe..0000000 --- a/examples/hello-owl/constraints.md +++ /dev/null @@ -1,25 +0,0 @@ -# constraints - -## language - -- TypeScript with ES modules -- Node.js runtime -- no external dependencies beyond Node built-ins - -## structure - -``` -hello-owl/ - src/ - greeter.ts - formatter.ts - cli.ts - package.json - tsconfig.json -``` - -## conventions - -- functions export as named exports -- pure functions where possible (greeter, formatter) -- cli handles process args and output diff --git a/examples/hello-owl/product.md b/examples/hello-owl/product.md deleted file mode 100644 index 452551a..0000000 --- a/examples/hello-owl/product.md +++ /dev/null @@ -1,21 +0,0 @@ -# hello-owl - -a minimal example for testing multi-agent build protocol (MABP). - -## purpose - -demonstrate coordinated building with dependency ordering: -- two components can build in parallel (greeter, formatter) -- one component depends on both (cli) - -## components - -- **greeter**: generates greeting messages -- **formatter**: styles/decorates text output -- **cli**: command-line entry point, combines greeter + formatter - -## success criteria - -- `hello-owl Alice` outputs styled greeting -- each component buildable independently -- dependency chain enforced (cli waits for greeter + formatter) diff --git a/mabp-api/index.js b/examples/multi-agent-build/impl/api/index.js similarity index 100% rename from mabp-api/index.js rename to examples/multi-agent-build/impl/api/index.js diff --git a/mabp-api/marketplace-aggregator.js b/examples/multi-agent-build/impl/api/marketplace-aggregator.js similarity index 100% rename from mabp-api/marketplace-aggregator.js rename to examples/multi-agent-build/impl/api/marketplace-aggregator.js diff --git a/mabp-api/package-lock.json b/examples/multi-agent-build/impl/api/package-lock.json similarity index 100% rename from mabp-api/package-lock.json rename to examples/multi-agent-build/impl/api/package-lock.json diff --git a/mabp-api/package.json b/examples/multi-agent-build/impl/api/package.json similarity index 100% rename from mabp-api/package.json rename to examples/multi-agent-build/impl/api/package.json diff --git a/mabp-dashboard/index.html b/examples/multi-agent-build/impl/dashboard/index.html similarity index 100% rename from mabp-dashboard/index.html rename to examples/multi-agent-build/impl/dashboard/index.html diff --git a/mabp-dashboard/package.json b/examples/multi-agent-build/impl/dashboard/package.json similarity index 100% rename from mabp-dashboard/package.json rename to examples/multi-agent-build/impl/dashboard/package.json diff --git a/mabp-dashboard/server.js b/examples/multi-agent-build/impl/dashboard/server.js similarity index 100% rename from mabp-dashboard/server.js rename to examples/multi-agent-build/impl/dashboard/server.js diff --git a/multi-agent-build-owl/SKILL.md b/examples/multi-agent-build/spec/SKILL.md similarity index 100% rename from multi-agent-build-owl/SKILL.md rename to examples/multi-agent-build/spec/SKILL.md diff --git a/multi-agent-build-owl/behaviors/build-flow.md b/examples/multi-agent-build/spec/behaviors/build-flow.md similarity index 100% rename from multi-agent-build-owl/behaviors/build-flow.md rename to examples/multi-agent-build/spec/behaviors/build-flow.md diff --git a/multi-agent-build-owl/behaviors/failure.md b/examples/multi-agent-build/spec/behaviors/failure.md similarity index 100% rename from multi-agent-build-owl/behaviors/failure.md rename to examples/multi-agent-build/spec/behaviors/failure.md diff --git a/multi-agent-build-owl/components/auditor.md b/examples/multi-agent-build/spec/components/auditor.md similarity index 100% rename from multi-agent-build-owl/components/auditor.md rename to examples/multi-agent-build/spec/components/auditor.md diff --git a/multi-agent-build-owl/components/builder.md b/examples/multi-agent-build/spec/components/builder.md similarity index 100% rename from multi-agent-build-owl/components/builder.md rename to examples/multi-agent-build/spec/components/builder.md diff --git a/multi-agent-build-owl/components/coordinator.md b/examples/multi-agent-build/spec/components/coordinator.md similarity index 100% rename from multi-agent-build-owl/components/coordinator.md rename to examples/multi-agent-build/spec/components/coordinator.md diff --git a/multi-agent-build-owl/components/integrator.md b/examples/multi-agent-build/spec/components/integrator.md similarity index 100% rename from multi-agent-build-owl/components/integrator.md rename to examples/multi-agent-build/spec/components/integrator.md diff --git a/multi-agent-build-owl/constraints.md b/examples/multi-agent-build/spec/constraints.md similarity index 100% rename from multi-agent-build-owl/constraints.md rename to examples/multi-agent-build/spec/constraints.md diff --git a/multi-agent-build-owl/coordinator/README.md b/examples/multi-agent-build/spec/coordinator/README.md similarity index 100% rename from multi-agent-build-owl/coordinator/README.md rename to examples/multi-agent-build/spec/coordinator/README.md diff --git a/multi-agent-build-owl/coordinator/index.js b/examples/multi-agent-build/spec/coordinator/index.js similarity index 100% rename from multi-agent-build-owl/coordinator/index.js rename to examples/multi-agent-build/spec/coordinator/index.js diff --git a/multi-agent-build-owl/coordinator/package-lock.json b/examples/multi-agent-build/spec/coordinator/package-lock.json similarity index 100% rename from multi-agent-build-owl/coordinator/package-lock.json rename to examples/multi-agent-build/spec/coordinator/package-lock.json diff --git a/multi-agent-build-owl/coordinator/package.json b/examples/multi-agent-build/spec/coordinator/package.json similarity index 100% rename from multi-agent-build-owl/coordinator/package.json rename to examples/multi-agent-build/spec/coordinator/package.json diff --git a/multi-agent-build-owl/product.md b/examples/multi-agent-build/spec/product.md similarity index 100% rename from multi-agent-build-owl/product.md rename to examples/multi-agent-build/spec/product.md diff --git a/poll/backend/index.js b/examples/poll/impl/backend/index.js similarity index 100% rename from poll/backend/index.js rename to examples/poll/impl/backend/index.js diff --git a/poll/backend/package-lock.json b/examples/poll/impl/backend/package-lock.json similarity index 100% rename from poll/backend/package-lock.json rename to examples/poll/impl/backend/package-lock.json diff --git a/poll/backend/package.json b/examples/poll/impl/backend/package.json similarity index 100% rename from poll/backend/package.json rename to examples/poll/impl/backend/package.json diff --git a/poll/frontend/index.html b/examples/poll/impl/frontend/index.html similarity index 100% rename from poll/frontend/index.html rename to examples/poll/impl/frontend/index.html diff --git a/poll/frontend/package-lock.json b/examples/poll/impl/frontend/package-lock.json similarity index 100% rename from poll/frontend/package-lock.json rename to examples/poll/impl/frontend/package-lock.json diff --git a/poll/frontend/package.json b/examples/poll/impl/frontend/package.json similarity index 100% rename from poll/frontend/package.json rename to examples/poll/impl/frontend/package.json diff --git a/poll/frontend/src/App.jsx b/examples/poll/impl/frontend/src/App.jsx similarity index 100% rename from poll/frontend/src/App.jsx rename to examples/poll/impl/frontend/src/App.jsx diff --git a/poll/frontend/src/main.jsx b/examples/poll/impl/frontend/src/main.jsx similarity index 100% rename from poll/frontend/src/main.jsx rename to examples/poll/impl/frontend/src/main.jsx diff --git a/poll/frontend/src/styles.css b/examples/poll/impl/frontend/src/styles.css similarity index 100% rename from poll/frontend/src/styles.css rename to examples/poll/impl/frontend/src/styles.css diff --git a/poll/frontend/vite.config.js b/examples/poll/impl/frontend/vite.config.js similarity index 100% rename from poll/frontend/vite.config.js rename to examples/poll/impl/frontend/vite.config.js diff --git a/poll-owl/components/api.md b/examples/poll/spec/components/api.md similarity index 100% rename from poll-owl/components/api.md rename to examples/poll/spec/components/api.md diff --git a/poll-owl/components/web.md b/examples/poll/spec/components/web.md similarity index 100% rename from poll-owl/components/web.md rename to examples/poll/spec/components/web.md diff --git a/poll-owl/constraints.md b/examples/poll/spec/constraints.md similarity index 100% rename from poll-owl/constraints.md rename to examples/poll/spec/constraints.md diff --git a/poll-owl/product.md b/examples/poll/spec/product.md similarity index 100% rename from poll-owl/product.md rename to examples/poll/spec/product.md diff --git a/todo/backend/index.js b/examples/todo/impl/backend/index.js similarity index 100% rename from todo/backend/index.js rename to examples/todo/impl/backend/index.js diff --git a/todo/backend/index.test.js b/examples/todo/impl/backend/index.test.js similarity index 100% rename from todo/backend/index.test.js rename to examples/todo/impl/backend/index.test.js diff --git a/todo/backend/package-lock.json b/examples/todo/impl/backend/package-lock.json similarity index 100% rename from todo/backend/package-lock.json rename to examples/todo/impl/backend/package-lock.json diff --git a/todo/backend/package.json b/examples/todo/impl/backend/package.json similarity index 100% rename from todo/backend/package.json rename to examples/todo/impl/backend/package.json diff --git a/todo/frontend/index.html b/examples/todo/impl/frontend/index.html similarity index 100% rename from todo/frontend/index.html rename to examples/todo/impl/frontend/index.html diff --git a/todo/frontend/package-lock.json b/examples/todo/impl/frontend/package-lock.json similarity index 100% rename from todo/frontend/package-lock.json rename to examples/todo/impl/frontend/package-lock.json diff --git a/todo/frontend/package.json b/examples/todo/impl/frontend/package.json similarity index 100% rename from todo/frontend/package.json rename to examples/todo/impl/frontend/package.json diff --git a/todo/frontend/src/App.jsx b/examples/todo/impl/frontend/src/App.jsx similarity index 100% rename from todo/frontend/src/App.jsx rename to examples/todo/impl/frontend/src/App.jsx diff --git a/todo/frontend/src/App.test.jsx b/examples/todo/impl/frontend/src/App.test.jsx similarity index 100% rename from todo/frontend/src/App.test.jsx rename to examples/todo/impl/frontend/src/App.test.jsx diff --git a/todo/frontend/src/error-handler.js b/examples/todo/impl/frontend/src/error-handler.js similarity index 100% rename from todo/frontend/src/error-handler.js rename to examples/todo/impl/frontend/src/error-handler.js diff --git a/todo/frontend/src/main.jsx b/examples/todo/impl/frontend/src/main.jsx similarity index 100% rename from todo/frontend/src/main.jsx rename to examples/todo/impl/frontend/src/main.jsx diff --git a/todo/frontend/src/styles.css b/examples/todo/impl/frontend/src/styles.css similarity index 100% rename from todo/frontend/src/styles.css rename to examples/todo/impl/frontend/src/styles.css diff --git a/todo/frontend/src/test-setup.js b/examples/todo/impl/frontend/src/test-setup.js similarity index 100% rename from todo/frontend/src/test-setup.js rename to examples/todo/impl/frontend/src/test-setup.js diff --git a/todo/frontend/vite.config.js b/examples/todo/impl/frontend/vite.config.js similarity index 100% rename from todo/frontend/vite.config.js rename to examples/todo/impl/frontend/vite.config.js diff --git a/todo-owl/components/api.md b/examples/todo/spec/components/api.md similarity index 100% rename from todo-owl/components/api.md rename to examples/todo/spec/components/api.md diff --git a/todo-owl/components/web.md b/examples/todo/spec/components/web.md similarity index 100% rename from todo-owl/components/web.md rename to examples/todo/spec/components/web.md diff --git a/todo-owl/constraints.md b/examples/todo/spec/constraints.md similarity index 100% rename from todo-owl/constraints.md rename to examples/todo/spec/constraints.md diff --git a/todo-owl/product.md b/examples/todo/spec/product.md similarity index 100% rename from todo-owl/product.md rename to examples/todo/spec/product.md diff --git a/owl/SKILL.md b/owl/SKILL.md deleted file mode 100644 index 0245e5a..0000000 --- a/owl/SKILL.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -name: owl -description: Build products from natural language specs -version: 0.1.0 ---- - -# owl - -Describe what you want in markdown, run /owl apply, and it gets built. - -## Commands - -### /owl apply - -Implement the specs in the current directory. - -1. Read product.md to understand what we're building -2. Follow markdown links to gather component and behavior specs -3. Read constraints.md for rules to follow -4. Implement each component one at a time -5. Verify each matches its spec before moving on - -Rules: -- Never modify spec files -- Follow constraints strictly -- Be minimal - do not add features not in spec -- Stop and ask if spec is ambiguous - -### /owl status - -Compare specs to codebase. Report: -- What is specified but missing -- What exists but is not specified -- What contradicts the spec - -### /owl plan - -Show what would change without implementing.