design_doc · markdown

Project Structure + Backlog Design

Project Structure + Backlog Design Date: 2026 04 23 Status: Approved Problem No persistent, machine readable record of what work is active or queued. At session start, Justin must reconstruct intent from conversation. Atlas has no "what are we building" signal beyond session summaries and memory search. Secondary: docs/ accumulated files from multiple conven...

Date: 2026-04-23 Status: Approved

---

Problem

No persistent, machine-readable record of what work is active or queued. At session start, Justin must reconstruct intent from conversation. Atlas has no "what are we building" signal beyond session summaries and memory search.

Secondary: docs/ accumulated files from multiple conventions with no clear separation between platform docs and client docs.

---

Two Layers of Work

RedKey (platform) — work on the engine, agents, HCS infra, Atlas. Lives in this repo forever.

Client deployments — projects that run *through* RedKey (CCOS2, CCOS3, future clients). Each client gets their own repo eventually. This repo holds a bootstrap stub until migration.

---

Folder Structure

``redkey/ backlog.yaml ← platform work items (RedKey engine, infra, Atlas) ccos2/ backlog.yaml ← CCOS2 work items (migrates to ccos2 repo) docs/ ← CCOS2 specs, briefs, design docs (migrates) definitions/ ← agent definitions (already exists) docs/ ← platform docs only execution-model.md topic-map.md roadmap.md plans/ ← dated implementation plans specs/ ← dated design specs ideas/ ← vision/exploration docs``

Client migration: when CCOS2 gets its own repo, ccos2/ lifts out wholesale. No restructuring needed.

---

Backlog Schema

```yaml

backlog.yaml

id: slug-style-id

done items stay in the file as audit trail — Atlas filters them out at session start
You own the file. Atlas proposes changes mid-session; you commit.
One backlog per layer: backlog.yaml (platform), ccos2/backlog.yaml (CCOS2)

---

Atlas Context Injection

scripts/atlas-context.js gets a new Active Work section injected before recent sessions. Logic:

1. Read backlog.yaml from repo root 2. If ATLAS_CLIENT_ID matches a client folder (e.g. ccos2), also read ccos2/backlog.yaml 3. Filter out status: done, sort by priority 4. Output as a markdown block:

```

Active Work

Platform 1. [active] quinn-step3 — Check Quinn completed marketing site step 3 2. [queued] project-planning-design — Design phase/depends_on model for Claire + Engine

CCOS2 1. [active] marketing-site — redkey-marketing-site workflow in progress ```

If no backlog file exists, section is omitted silently.

---

Docs Convention

| Type | Location | |---|---| | Platform architecture docs | docs/ root | | Design specs | docs/specs/YYYY-MM-DD-<topic>-design.md | | Implementation plans | docs/plans/YYYY-MM-DD-<topic>.md | | Ideas / exploration | docs/ideas/ | | Client specs + briefs | ccos2/docs/ (or <client>/docs/) |

docs/superpowers/ is removed. CLAUDE.md declares docs/specs/ as the canonical spec location — this overrides the brainstorming skill default.

---

What This Is Not

Not a Supabase-backed work queue. That's Phase 3+ if needed.
Not agent-writable autonomously. Agents propose; humans commit.
Not a project management system. One flat prioritized list per layer is enough for now.

---

Implementation

1. Create backlog.yaml at root with current platform items 2. Create ccos2/backlog.yaml with current CCOS2 items 3. Create ccos2/docs/ folder 4. Update scripts/atlas-context.js to inject Active Work section 5. Update redkey.yaml atlas section to reference atlas.sh (not run-architect.sh)