spec: verify SPEC.md, decompose into sub-specs, scaffold plan#1
spec: verify SPEC.md, decompose into sub-specs, scaffold plan#1
Conversation
Product charter for bots.ac with verification-pass edits folded in (placeholder resolution, ambiguity fixes, Foundations stubs). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Brainstorm output for how SPEC.md is split into executable sub-specs (docs/superpowers/specs/) plus the implementation plan for creating the scaffolding (docs/superpowers/plans/). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Body of research informing the "self-learning agent review" gate and the Web Agent's browsing strategy layer. Referenced from SPEC.md. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Web Agent SelfEvolvingAgent block and Self-learning agent review section now point at docs/self-learning-agents/ so the research material is discoverable from the charter. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Task 2 registry preamble and Task 5 12-web-agent stub now point at docs/self-learning-agents/ so subagents writing these stubs include the reference from the first write. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
- Fix separator row column 2: reduce 30 dashes to 29 to match header - Fix MVP cut row: remove extra trailing space before closing pipe Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 67932f5be3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| ## High confidence | ||
|
|
||
| ### [High] EvoTest: Evolutionary Test‑Time Learning for Self‑Improving Agentic Systems ([paper](research/self-learning-agents/evotest/PAPER.md)) |
There was a problem hiding this comment.
docs/SELF_LEARNING_AGENTS.md links papers as research/self-learning-agents/..., but from this file that resolves to docs/research/..., and those targets do not exist (the paper notes are under docs/self-learning-agents/...). As written, the report’s paper links are broken, so readers cannot navigate from the summary to the referenced source notes.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
Adds a first-committed product charter (SPEC.md) and supporting documentation to decompose that charter into a registry + sub-spec stub set, along with a research corpus and summary for “self-learning agents” techniques referenced by the charter.
Changes:
- Add
SPEC.mdproduct charter with a pointer to the sub-spec registry. - Introduce spec decomposition strategy + a scaffolding implementation plan to drive future drafting/implementation.
- Add
docs/decomposition.mdregistry, 25 sub-spec stub docs, and self-learning-agent research notes + summaries.
Reviewed changes
Copilot reviewed 48 out of 48 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
SPEC.md |
Product charter for bots.ac; now points readers to the sub-spec registry. |
docs/decomposition.md |
Central registry/index for sub-spec IDs, dependencies, phase, and MVP cut line. |
docs/SELF_LEARNING_AGENTS.md |
Curated summary of the self-learning agents paper set. |
docs/superpowers/specs/2026-04-16-spec-decomposition-strategy-design.md |
Defines decomposition rules, templates, dependency/approval rules, and versioning approach. |
docs/superpowers/plans/2026-04-16-spec-decomposition-scaffolding.md |
Step-by-step plan to scaffold the registry + stubs. |
docs/specs/00-workspace-shell.md |
Stub sub-spec for workspace shell. |
docs/specs/01-persistent-compute.md |
Stub sub-spec for persistent compute. |
docs/specs/02-code-agent.md |
Stub sub-spec for code agent. |
docs/specs/03-audit-log.md |
Stub sub-spec for audit log. |
docs/specs/10-router-agent.md |
Stub sub-spec for router agent. |
docs/specs/11-skills-loader.md |
Stub sub-spec for skills loader. |
docs/specs/12-web-agent.md |
Stub sub-spec for web agent. |
docs/specs/13-inbox-agent.md |
Stub sub-spec for inbox agent. |
docs/specs/14-media-agent.md |
Stub sub-spec for media agent. |
docs/specs/20-natural-language-scheduler.md |
Stub sub-spec for natural-language scheduler. |
docs/specs/21-trigger-engine.md |
Stub sub-spec for trigger engine/webhooks. |
docs/specs/22-integration-framework.md |
Stub sub-spec for integrations framework. |
docs/specs/23-memory-system.md |
Stub sub-spec for memory system. |
docs/specs/24-cache-layer.md |
Stub sub-spec for cache layer. |
docs/specs/25-model-routing.md |
Stub sub-spec for model routing. |
docs/specs/26-approvals-and-safety.md |
Stub sub-spec for approvals and safety. |
docs/specs/27-observability.md |
Stub sub-spec for observability. |
docs/specs/28-delivery-surfaces.md |
Stub sub-spec for delivery surfaces. |
docs/specs/f-identity-and-auth.md |
Foundation stub for identity/auth. |
docs/specs/f-workspace-policy.md |
Foundation stub for workspace policy. |
docs/specs/f-billing-and-cost.md |
Foundation stub for billing/cost surface. |
docs/specs/f-multi-tenant-isolation.md |
Foundation stub for multi-tenant isolation. |
docs/specs/f-data-retention.md |
Foundation stub for data retention/deletion. |
docs/specs/f-public-api.md |
Foundation stub for public API. |
docs/specs/f-compliance-posture.md |
Foundation stub for compliance posture. |
docs/self-learning-agents/aflow/PAPER.md |
Paper summary/extracts for AFLOW. |
docs/self-learning-agents/agentgen/PAPER.md |
Paper summary/extracts for AgentGen. |
docs/self-learning-agents/aria/PAPER.md |
Paper summary/extracts for ARIA. |
docs/self-learning-agents/evoagentx/PAPER.md |
Paper notes/extracts for EvoAgentX. |
docs/self-learning-agents/evotest/PAPER.md |
Paper summary/extracts for EvoTest. |
docs/self-learning-agents/learn_by_interact/PAPER.md |
Paper summary/extracts for Learn-by-interact. |
docs/self-learning-agents/mem0/PAPER.md |
Paper summary/extracts for Mem0. |
docs/self-learning-agents/meminsight/PAPER.md |
Paper summary/extracts for MemInsight. |
docs/self-learning-agents/memory_os/PAPER.md |
Paper summary/extracts for MemoryOS. |
docs/self-learning-agents/reflexion/PAPER.md |
Paper summary/extracts for Reflexion. |
docs/self-learning-agents/sage/PAPER.md |
Paper summary/extracts for SAGE. |
docs/self-learning-agents/self/PAPER.md |
Paper summary/extracts for SELF. |
docs/self-learning-agents/self_challenging_language_model_agents/PAPER.md |
Paper summary/extracts for Self-Challenging agents. |
docs/self-learning-agents/self_evolving_curriculum/PAPER.md |
Paper summary/extracts for SEC. |
docs/self-learning-agents/self_reasoning_language_models/PAPER.md |
Paper summary/extracts for SRLM. |
docs/self-learning-agents/self_refine/PAPER.md |
Paper summary/extracts for SELF-REFINE. |
docs/self-learning-agents/self_rewarding_self_improving/PAPER.md |
Paper summary/extracts for RLSR. |
docs/self-learning-agents/vision_zero/PAPER.md |
Paper summary/extracts for Vision-Zero. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| * [EvoTest](#high-evo-test-evolutionary-test-time-learning-for-self-improving-agentic-systems) | ||
| * [SAGE](#high-self-evolving-agents-with-reflective-and-memory-augmented-abilities-sage) | ||
| * [Mem0](#high-mem0-building-production-ready-ai-agents-with-scalable-long-term-memory) | ||
| * [EvoAgentX](#high-evoagentx-an-automated-framework-for-evolving-agentic-workflows) | ||
|
|
||
| * [Medium confidence](#medium-confidence) | ||
| * [MemInsight](#medium-meminsight-autonomous-memory-augmentation-for-llm-agents) | ||
| * [MemoryOS](#medium-memory-os-of-ai-agent) | ||
| * [AFLOW](#medium-aflow-automating-agentic-workflow-generation) | ||
| * [Self‑Reasoning Language Models](#medium-self-reasoning-language-models) | ||
| * [Self‑Challenging Language Model Agents](#medium-self-challenging-language-model-agents) | ||
| * [Self‑Refine](#medium-self-refine-iterative-refinement-with-self-feedback) | ||
| * [Reflexion](#medium-reflexion-language-agents-with-verbal-reinforcement-learning) | ||
| * [SELF](#medium-self-self-evolution-with-language-feedback) | ||
| * [ARIA](#medium-enabling-self-improving-agents-to-learn-at-test-time-with-human-in-the-loop-guidance-aria) | ||
|
|
||
| * [Low confidence](#low-confidence) | ||
| * [AgentGen](#low-agentgen-enhancing-planning-abilities-for-large-language-model-based-agents-via-environment-and-task-generation) | ||
| * [Learn‑by‑interact](#low-learn-by-interact-a-data-centric-framework-for-self-adaptive-agents-in-realistic-environments) | ||
| * [RLSR](#low-self-rewarding-self-improving-rlsr) | ||
| * [Self‑Evolving Curriculum](#low-self-evolving-curriculum-for-llm-reasoning-sec) | ||
| * [Vision‑Zero](#low-vision-zero-scalable-vlm-self-evolution-via-multi-agent-self-play) |
There was a problem hiding this comment.
The manual Table of Contents links appear to use anchor slugs that won’t match GitHub’s generated heading IDs (e.g., #high-evo-test-... vs the actual heading text EvoTest). This will make the ToC links broken in rendered Markdown; consider regenerating the anchors to match GitHub’s slugging rules or removing the manual ToC in favor of a simpler section list.
| * [EvoTest](#high-evo-test-evolutionary-test-time-learning-for-self-improving-agentic-systems) | |
| * [SAGE](#high-self-evolving-agents-with-reflective-and-memory-augmented-abilities-sage) | |
| * [Mem0](#high-mem0-building-production-ready-ai-agents-with-scalable-long-term-memory) | |
| * [EvoAgentX](#high-evoagentx-an-automated-framework-for-evolving-agentic-workflows) | |
| * [Medium confidence](#medium-confidence) | |
| * [MemInsight](#medium-meminsight-autonomous-memory-augmentation-for-llm-agents) | |
| * [MemoryOS](#medium-memory-os-of-ai-agent) | |
| * [AFLOW](#medium-aflow-automating-agentic-workflow-generation) | |
| * [Self‑Reasoning Language Models](#medium-self-reasoning-language-models) | |
| * [Self‑Challenging Language Model Agents](#medium-self-challenging-language-model-agents) | |
| * [Self‑Refine](#medium-self-refine-iterative-refinement-with-self-feedback) | |
| * [Reflexion](#medium-reflexion-language-agents-with-verbal-reinforcement-learning) | |
| * [SELF](#medium-self-self-evolution-with-language-feedback) | |
| * [ARIA](#medium-enabling-self-improving-agents-to-learn-at-test-time-with-human-in-the-loop-guidance-aria) | |
| * [Low confidence](#low-confidence) | |
| * [AgentGen](#low-agentgen-enhancing-planning-abilities-for-large-language-model-based-agents-via-environment-and-task-generation) | |
| * [Learn‑by‑interact](#low-learn-by-interact-a-data-centric-framework-for-self-adaptive-agents-in-realistic-environments) | |
| * [RLSR](#low-self-rewarding-self-improving-rlsr) | |
| * [Self‑Evolving Curriculum](#low-self-evolving-curriculum-for-llm-reasoning-sec) | |
| * [Vision‑Zero](#low-vision-zero-scalable-vlm-self-evolution-via-multi-agent-self-play) | |
| * [Medium confidence](#medium-confidence) | |
| * [Low confidence](#low-confidence) |
| ### [High] EvoTest: Evolutionary Test‑Time Learning for Self‑Improving Agentic Systems ([paper](research/self-learning-agents/evotest/PAPER.md)) | ||
|
|
||
| EvoTest uses an evolutionary algorithm to adapt an agent’s prompt, memory and tool configuration between episodes. An **Actor Agent** performs the task while an **Evolver Agent** proposes new configurations based on a fitness function【866554534294018†L0-L111】. The authors introduce the **J‑TTL benchmark** to evaluate test‑time learning and show that evolutionary search yields improved performance without gradient‑based fine‑tuning【866554534294018†L110-L145】. This technique could enable automatic agent‑creator functionality in our runtime, making it highly relevant. | ||
|
|
||
| ### [High] Self‑Evolving Agents with Reflective and Memory‑Augmented Abilities (SAGE) ([paper](research/self-learning-agents/sage/PAPER.md)) | ||
|
|
||
| SAGE combines a **reflection mechanism** with a **memory optimisation module** based on the Ebbinghaus forgetting curve【64826999719218†L18-L27】. Three cooperating agents (User, Assistant and Checker) iteratively evaluate outputs and decide what information to retain【64826999719218†L28-L33】. SAGE significantly improves both proprietary and open‑source models and demonstrates how reflective feedback and selective memory can drive self‑evolution【64826999719218†L93-L99】. These ideas could inform our auto‑generated agent and memory design, so we assign high confidence. | ||
|
|
||
| ### [High] Mem0: Building Production‑Ready AI Agents with Scalable Long‑Term Memory ([paper](research/self-learning-agents/mem0/PAPER.md)) | ||
|
|
||
| Mem0 tackles the fixed context window problem by dynamically extracting and consolidating salient information from conversations and storing it in a scalable, graph‑structured memory【233045525579731†L8-L23】. The architecture consistently outperforms retrieval‑augmented and full‑context baselines while reducing latency and token cost【233045525579731†L16-L37】. Its production focus and memory management techniques make it highly relevant for our persistent compute layer. | ||
|
|
||
| ### [High] EvoAgentX: An Automated Framework for Evolving Agentic Workflows ([paper](research/self-learning-agents/evoagentx/PAPER.md)) | ||
|
|
||
| EvoAgentX is an open‑source platform that automates the generation, execution and evolutionary optimisation of multi‑agent workflows. It provides a modular architecture and integrates optimisation algorithms like TextGrad, AFlow and MIPRO to refine prompts, tool configurations and workflow topologies. Experiments show significant improvements across reasoning, code generation and real‑world tasks. The system demonstrates an end‑to‑end workflow evolution pipeline, directly inspiring our support for auto‑generated agents. | ||
|
|
||
| ## Medium confidence | ||
|
|
||
| ### [Medium] MemInsight: Autonomous Memory Augmentation for LLM Agents ([paper](research/self-learning-agents/meminsight/PAPER.md)) |
There was a problem hiding this comment.
The [paper](research/self-learning-agents/.../PAPER.md) links don’t match the repository layout (the papers live under docs/self-learning-agents/). As written, these links will be broken; update them to the correct relative paths from this file.
| ### [High] EvoTest: Evolutionary Test‑Time Learning for Self‑Improving Agentic Systems ([paper](research/self-learning-agents/evotest/PAPER.md)) | |
| EvoTest uses an evolutionary algorithm to adapt an agent’s prompt, memory and tool configuration between episodes. An **Actor Agent** performs the task while an **Evolver Agent** proposes new configurations based on a fitness function【866554534294018†L0-L111】. The authors introduce the **J‑TTL benchmark** to evaluate test‑time learning and show that evolutionary search yields improved performance without gradient‑based fine‑tuning【866554534294018†L110-L145】. This technique could enable automatic agent‑creator functionality in our runtime, making it highly relevant. | |
| ### [High] Self‑Evolving Agents with Reflective and Memory‑Augmented Abilities (SAGE) ([paper](research/self-learning-agents/sage/PAPER.md)) | |
| SAGE combines a **reflection mechanism** with a **memory optimisation module** based on the Ebbinghaus forgetting curve【64826999719218†L18-L27】. Three cooperating agents (User, Assistant and Checker) iteratively evaluate outputs and decide what information to retain【64826999719218†L28-L33】. SAGE significantly improves both proprietary and open‑source models and demonstrates how reflective feedback and selective memory can drive self‑evolution【64826999719218†L93-L99】. These ideas could inform our auto‑generated agent and memory design, so we assign high confidence. | |
| ### [High] Mem0: Building Production‑Ready AI Agents with Scalable Long‑Term Memory ([paper](research/self-learning-agents/mem0/PAPER.md)) | |
| Mem0 tackles the fixed context window problem by dynamically extracting and consolidating salient information from conversations and storing it in a scalable, graph‑structured memory【233045525579731†L8-L23】. The architecture consistently outperforms retrieval‑augmented and full‑context baselines while reducing latency and token cost【233045525579731†L16-L37】. Its production focus and memory management techniques make it highly relevant for our persistent compute layer. | |
| ### [High] EvoAgentX: An Automated Framework for Evolving Agentic Workflows ([paper](research/self-learning-agents/evoagentx/PAPER.md)) | |
| EvoAgentX is an open‑source platform that automates the generation, execution and evolutionary optimisation of multi‑agent workflows. It provides a modular architecture and integrates optimisation algorithms like TextGrad, AFlow and MIPRO to refine prompts, tool configurations and workflow topologies. Experiments show significant improvements across reasoning, code generation and real‑world tasks. The system demonstrates an end‑to‑end workflow evolution pipeline, directly inspiring our support for auto‑generated agents. | |
| ## Medium confidence | |
| ### [Medium] MemInsight: Autonomous Memory Augmentation for LLM Agents ([paper](research/self-learning-agents/meminsight/PAPER.md)) | |
| ### [High] EvoTest: Evolutionary Test‑Time Learning for Self‑Improving Agentic Systems ([paper](self-learning-agents/evotest/PAPER.md)) | |
| EvoTest uses an evolutionary algorithm to adapt an agent’s prompt, memory and tool configuration between episodes. An **Actor Agent** performs the task while an **Evolver Agent** proposes new configurations based on a fitness function【866554534294018†L0-L111】. The authors introduce the **J‑TTL benchmark** to evaluate test‑time learning and show that evolutionary search yields improved performance without gradient‑based fine‑tuning【866554534294018†L110-L145】. This technique could enable automatic agent‑creator functionality in our runtime, making it highly relevant. | |
| ### [High] Self‑Evolving Agents with Reflective and Memory‑Augmented Abilities (SAGE) ([paper](self-learning-agents/sage/PAPER.md)) | |
| SAGE combines a **reflection mechanism** with a **memory optimisation module** based on the Ebbinghaus forgetting curve【64826999719218†L18-L27】. Three cooperating agents (User, Assistant and Checker) iteratively evaluate outputs and decide what information to retain【64826999719218†L28-L33】. SAGE significantly improves both proprietary and open‑source models and demonstrates how reflective feedback and selective memory can drive self‑evolution【64826999719218†L93-L99】. These ideas could inform our auto‑generated agent and memory design, so we assign high confidence. | |
| ### [High] Mem0: Building Production‑Ready AI Agents with Scalable Long‑Term Memory ([paper](self-learning-agents/mem0/PAPER.md)) | |
| Mem0 tackles the fixed context window problem by dynamically extracting and consolidating salient information from conversations and storing it in a scalable, graph‑structured memory【233045525579731†L8-L23】. The architecture consistently outperforms retrieval‑augmented and full‑context baselines while reducing latency and token cost【233045525579731†L16-L37】. Its production focus and memory management techniques make it highly relevant for our persistent compute layer. | |
| ### [High] EvoAgentX: An Automated Framework for Evolving Agentic Workflows ([paper](self-learning-agents/evoagentx/PAPER.md)) | |
| EvoAgentX is an open‑source platform that automates the generation, execution and evolutionary optimisation of multi‑agent workflows. It provides a modular architecture and integrates optimisation algorithms like TextGrad, AFlow and MIPRO to refine prompts, tool configurations and workflow topologies. Experiments show significant improvements across reasoning, code generation and real‑world tasks. The system demonstrates an end‑to‑end workflow evolution pipeline, directly inspiring our support for auto‑generated agents. | |
| ## Medium confidence | |
| ### [Medium] MemInsight: Autonomous Memory Augmentation for LLM Agents ([paper](self-learning-agents/meminsight/PAPER.md)) |
| ## Prerequisite | ||
|
|
||
| The plan edits `SPEC.md`, which currently lives on the main branch at `/Users/droxey/dev/repos/bots.ac/SPEC.md`. The worktree (`.claude/worktrees/adoring-banach/`) contains only `README.md`. Before executing this plan: | ||
|
|
||
| **Option A (recommended):** Execute the plan directly in the main repo working tree (`/Users/droxey/dev/repos/bots.ac/`) on the main branch, since SPEC.md already has unstaged edits from the earlier verification pass. The scaffolding commit lands alongside those edits. | ||
|
|
||
| **Option B:** Cherry-pick or merge the SPEC.md edits into the worktree branch first, then execute here. More steps, same result. | ||
|
|
||
| The plan below uses repo-root-relative paths (e.g. `docs/decomposition.md`). Whichever option you pick, resolve those paths against the directory where SPEC.md lives. |
There was a problem hiding this comment.
This plan hard-codes local absolute paths like /Users/droxey/dev/repos/... and .claude/worktrees/..., which makes the doc non-portable and leaks a contributor’s local environment into the repo. Prefer repo-relative instructions (or describe prerequisites generically) so any contributor can follow the plan.
There was a problem hiding this comment.
@copilot apply changes based on this feedback
| - [ ] **Step 1: Write `docs/specs/f-identity-and-auth.md`** | ||
|
|
||
| ````markdown | ||
| # f-identity — Identity and authentication | ||
|
|
||
| **Status:** stub | ||
| **Phase:** foundation | ||
| **Depends on:** — | ||
| **Required for MVP:** yes |
There was a problem hiding this comment.
This step instructs creating docs/specs/f-identity-and-auth.md but the stub’s H1 uses # f-identity — .... That mismatch will break the plan’s own consistency checks (and creates confusion about the canonical ID). The H1 should use the same ID as the filename/registry (f-identity-and-auth).
There was a problem hiding this comment.
@copilot apply changes based on this feedback
There was a problem hiding this comment.
@copilot apply changes based on this feedback
There was a problem hiding this comment.
Fixed in b45f0f5. The stubs in the plan that used **Depends on:** f-identity have been updated to f-identity-and-auth (in f-public-api, 00-workspace-shell, 13-inbox-agent, and 22-integration-framework stub templates).
|
|
||
| SPEC.md is a product charter for bots.ac — a chat-first agent OS. A verification pass (`/Users/droxey/.claude/plans/mellow-cooking-wreath.md`) found that the spec is internally sound but too broad for a single implementation plan: it spans ~15 independent subsystems plus 7 foundational concerns that cut across all of them. | ||
|
|
There was a problem hiding this comment.
This document references a local verification-pass file path (/Users/droxey/.claude/plans/...). That path won’t exist for other contributors and reduces the doc’s usefulness; replace it with a repo-relative link (if checked in) or remove the machine-specific path.
There was a problem hiding this comment.
@copilot apply changes based on this feedback
There was a problem hiding this comment.
@copilot apply changes based on this feedback
There was a problem hiding this comment.
The hardcoded /Users/droxey/.claude/plans/... path was already removed from the Prerequisite section in a previous commit — that section now contains only generic repo-relative instructions. No further change needed here.
| | ID | Sub-spec | Why it's MVP | | ||
| |----|----------|--------------| | ||
| | f-identity | Identity & auth | Anyone using chat needs an account | | ||
| | f-workspace-policy | Workspace policy | Code Agent needs policy for destructive file changes | | ||
| | f-billing (thin) | Billing | Need a cost-unit model to log against; dashboards come later | | ||
| | 00 | workspace-shell | Chat UI, threads, file attachments | | ||
| | 01 | persistent-compute | The VM the Code Agent runs on | | ||
| | 02 | code-agent | The single agent MVP ships | | ||
| | 03 | audit-log | Required by product principle #3 (stay legible) | | ||
|
|
||
| Explicitly **not** MVP: router (trivial dispatch to code-agent suffices), skills-loader (code-agent can hardcode its skills initially), web/inbox/media agents, scheduler, triggers, integrations framework, memory system, model routing, approvals beyond workspace-policy basics, broader observability, public API, full billing dashboards, multi-tenant isolation beyond per-workspace VM. | ||
|
|
||
| **Cut line movement:** each move is a one-line PR to `decomposition.md` with a commit message explaining the tradeoff. That's the decision log — no separate log needed. | ||
|
|
||
| ## Adoption workflow | ||
|
|
||
| **Step 1 — Scaffolding (one PR)** | ||
| - Create `docs/decomposition.md` with the registry and cut line populated from SPEC.md. | ||
| - Create `docs/specs/` with one stub file per sub-spec: only the header block and a one-paragraph Context. Stubs take minutes each. | ||
| - Add one line at the top of SPEC.md: `See docs/decomposition.md for the sub-spec registry.` | ||
| - Land the scaffolding as a single atomic PR. | ||
|
|
||
| **Step 2 — Stubs → drafts (dependency order)** | ||
| - Start at the bottom of the graph: foundations first (`f-identity`, `f-workspace-policy`, `f-billing`). | ||
| - For each, run `/superpowers:brainstorming`. The brainstorming output fills in the template sections. Status moves `stub` → `drafted`. |
There was a problem hiding this comment.
The MVP-cut table and adoption workflow refer to foundation IDs like f-identity / f-billing, but the actual registry and filenames in this PR use f-identity-and-auth and f-billing-and-cost. Align the IDs in these examples so readers don’t copy/paste incorrect IDs into the registry or dependency lists.
There was a problem hiding this comment.
@copilot apply changes based on this feedback
There was a problem hiding this comment.
Fixed in b45f0f5. The example registry table (line 84) now uses f-identity-and-auth instead of f-identity. The MVP-cut table (line 175) and adoption workflow (line 196) were already using the correct full IDs.
- SELF_LEARNING_AGENTS.md: simplify ToC to top-level anchors only (nested per-paper anchors didn't match GitHub's generated heading slugs); fix all paper links from research/self-learning-agents/ → self-learning-agents/ - spec-decomposition-scaffolding.md: replace absolute local paths with repo-relative instructions; update Task 2 registry content and Task 3 stub H1 to use full IDs (f-identity-and-auth, f-billing-and-cost, etc.) - spec-decomposition-strategy-design.md: remove machine-specific plan path from Context; align MVP cut table and adoption workflow IDs with registry Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: adbd6ab375
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | f-compliance-posture | Compliance posture | stub | — | foundation | no | | ||
| | 00 | workspace-shell | stub | f-identity-and-auth | 1 | yes | | ||
| | 01 | persistent-compute | stub | 00, f-workspace-policy | 1 | yes | | ||
| | 02 | code-agent | stub | 01, 11 | 1 | yes | |
There was a problem hiding this comment.
02 is marked as required for MVP, but its dependency list includes 11 (skills-loader), which is below the MVP cut line and explicitly called out as non-MVP in the strategy doc (docs/superpowers/specs/2026-04-16-spec-decomposition-strategy-design.md, MVP section). This makes the cut line internally inconsistent and breaks dependency-based planning, because 02 cannot be completed without pulling in a slice that the registry says is out of MVP scope.
Useful? React with 👍 / 👎.
| | f-billing-and-cost | Billing and cost surface | stub | — | foundation | yes | | ||
| | f-multi-tenant-isolation | Multi-tenant isolation | stub | — | foundation | no | | ||
| | f-data-retention | Data retention and deletion | stub | — | foundation | no | | ||
| | f-public-api | Public API | stub | f-identity-and-auth | foundation | no | |
There was a problem hiding this comment.
The dependency model in docs/superpowers/specs/2026-04-16-spec-decomposition-strategy-design.md states that f-* foundation specs have no dependencies, but this registry row adds a dependency from f-public-api to f-identity-and-auth. That contradiction weakens the documented DAG rules and can cause status-gating checks or reviewer decisions to diverge depending on which document they follow.
Useful? React with 👍 / 👎.
- Remove 11 (skills-loader) from 02 (code-agent) depends-on: code-agent is above the MVP cut line; skills-loader is not. Strategy doc already says code-agent can hardcode its skills initially. Updated decomposition.md, 02-code-agent.md stub, and scaffolding plan Task 2 registry. - Clarify dependency model rule in strategy design: f-* specs may depend on other f-* specs (e.g. f-public-api → f-identity-and-auth). The rule "foundations have no dependencies" meant no numbered-spec deps, not no inter-foundation deps. Made the rule explicit. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Moves f-identity-and-auth from stub → drafted. Adds full design doc covering architecture (Supabase Auth + identity adapter), data model (users + workspace_members tables), interfaces (7 adapter functions), behavior (sign-in flow, magic link, username claim/rename, JWT validation), and verification checklist. Key decisions: Google + GitHub OAuth + magic link; personal workspaces only at launch; long-lived JWT (1 week, no refresh); role enum defined now (owner/admin/member/viewer), only owner assigned at launch; Supabase Auth behind a thin adapter for provider replaceability. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 107ab07b5b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| **Status values:** `stub` → `drafted` → `approved` → `in-flight` → `shipped`. | ||
|
|
||
| **MVP cut line:** a literal row in the table. Everything above it is required to ship the first release. Moving the line is a registry edit and a commit message. |
There was a problem hiding this comment.
The strategy doc defines the MVP cut as “everything above it is required,” but the actual registry keeps non-MVP foundation rows above the cut and then adds an exception (“plus the yes foundation rows”). This creates two incompatible interpretations of MVP scope, so reviewers or any status-gating automation following 2026-04-16-spec-decomposition-strategy-design.md will treat f-multi-tenant-isolation, f-data-retention, f-public-api, and f-compliance-posture as required when docs/decomposition.md says they are not. Please align one source of truth (either move non-MVP rows below the cut or update the strategy rule).
Useful? React with 👍 / 👎.
8-task TDD plan covering project foundation, DB migration, types/errors, Supabase client factory, username management, adapter core (getCurrentUser, getOptionalUser, requireAuth), membership functions, and public barrel with Supabase leakage grep check. All steps include complete code and expected test output. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Move the 4 non-MVP foundation rows (f-multi-tenant-isolation, f-data-retention, f-public-api, f-compliance-posture) below the MVP cut line so that "everything above the cut = required" holds without exception. Remove the "plus the yes foundation rows" caveat from both decomposition.md and the scaffolding plan's Task 2 registry content. The strategy design doc's rule and example were already correct. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 18cab7fd35
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…ds on fields and example registry table Agent-Logs-Url: https://github.com/musexmachine/bots.ac/sessions/d9d40571-0a30-4545-a782-5f2017d2d5f4 Co-authored-by: droxey <371368+droxey@users.noreply.github.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 76c0e8f194
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| user_id UUID PRIMARY KEY DEFAULT gen_random_uuid(), | ||
| supabase_user_id UUID UNIQUE NOT NULL, | ||
| email TEXT UNIQUE NOT NULL, | ||
| username CITEXT UNIQUE, |
There was a problem hiding this comment.
The migration allows users.username to be NULL, but the identity spec/types treat username as always present and the rest of the system relies on a global username@bots.ac namespace. If provisioning fails between user creation and username claim (or any future write path omits username), a row with NULL username can persist, violating that invariant and causing downstream logic to receive users that cannot be addressed by username.
Useful? React with 👍 / 👎.
| -- and the app layer never returns a User with a null username | ||
| CREATE TABLE IF NOT EXISTS users ( | ||
| user_id UUID PRIMARY KEY DEFAULT gen_random_uuid(), | ||
| supabase_user_id UUID UNIQUE NOT NULL, |
There was a problem hiding this comment.
supabase_user_id is documented as referencing auth.users.id, but the schema does not enforce that relationship. Without an actual foreign key, orphaned identity rows can accumulate when auth users are removed or IDs are inserted incorrectly, leading to stale usernames/emails that remain reserved and inconsistent auth state between Supabase and bots.ac data.
Useful? React with 👍 / 👎.
Summary
Verification pass and full decomposition scaffolding for `SPEC.md` (the bots.ac product charter). Splits the charter into 25 implementable sub-specs, commits the self-learning-agents research material, and sets up the registry + stub files ready for drafting.
What's in this PR
Status
All 8 scaffolding tasks complete and passing two-stage review (spec compliance + code quality). Final reviewer verdict: READY TO MERGE.
All changes are docs-only. No code, no build steps.
MVP cut line
The registry marks these sub-specs as required for the first release (above the cut line):
Next step
Run `/superpowers:brainstorming` on `f-identity-and-auth` (bottom of the dependency graph) to move the first sub-spec from `stub` → `drafted`.
Reviewer notes
🤖 Generated with Claude Code