From a0f79af2abf0449dff73f7023c46d0043baff695 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 22 Jun 2026 23:16:24 +0200 Subject: [PATCH] Normalize agent instructions and workplan frontmatter (STATE-WP-0067) - Align agent files with on-disk workplan prefixes (infer from workplan ids) - Set workplan domain to registered domain_slug; add topic_slug where applicable - Repair frontmatter delimiter formatting; migrate legacy task status literals - Regenerate AGENTS.md, CLAUDE.md, and .claude/rules from State Hub templates --- .claude/rules/agents.md | 14 +- .claude/rules/architecture.md | 21 +- .claude/rules/credential-routing.md | 6 +- .claude/rules/first-session.md | 15 +- .claude/rules/repo-boundary.md | 13 +- .claude/rules/repo-identity.md | 6 +- .claude/rules/session-protocol.md | 21 +- .claude/rules/stack-and-commands.md | 35 +-- .claude/rules/workplan-convention.md | 14 +- AGENTS.md | 285 ++++++------------ CLAUDE.md | 2 +- workplans/CYA-WP-0001-console-native-mvp.md | 2 +- .../CYA-WP-0002-memory-integration-roadmap.md | 2 +- ...ual-memory-activation-and-retrospection.md | 2 +- ...-0004-dev-install-and-release-packaging.md | 2 +- ...mory-profiles-and-phase-memory-feedback.md | 2 +- ...-WP-0006-profile-1-production-hardening.md | 2 +- .../CYA-WP-0007-interactive-shell-session.md | 2 +- ...WP-0008-llm-connect-adapter-integration.md | 2 +- 19 files changed, 148 insertions(+), 300 deletions(-) diff --git a/.claude/rules/agents.md b/.claude/rules/agents.md index b591868..0e8a5d9 100644 --- a/.claude/rules/agents.md +++ b/.claude/rules/agents.md @@ -1,15 +1,3 @@ -## Agent entry points - -| Runtime | Canonical instructions | -| --- | --- | -| **Grok / Codex** (shell) | `AGENTS.md` at repo root | -| **Claude Code** | This file tree via `CLAUDE.md` | - -`AGENTS.md` and `.claude/rules/` are kept in sync for repo-specific content. -Fleet-wide credential routing is mirrored in `credential-routing.md` and the -matching section of `AGENTS.md` — re-sync from `~/ops-warden/wiki/CredentialRouting.md` -when the catalog changes. - ## Kaizen Agents Specialized agent personas available on demand via the state-hub MCP. @@ -29,4 +17,4 @@ Common agents: | `project-management` | process | Track status, determine next steps | | `datamodel-optimization` | quality | Optimize dataclasses and data structures | -All 17 agents: call `list_kaizen_agents()` for the full list. \ No newline at end of file +All 17 agents: call `list_kaizen_agents()` for the full list. diff --git a/.claude/rules/architecture.md b/.claude/rules/architecture.md index ae6c786..7c2a645 100644 --- a/.claude/rules/architecture.md +++ b/.claude/rules/architecture.md @@ -1,23 +1,8 @@ ## Architecture -**Request pipeline** (`src/cya/orchestrator.py`): -1. Collect local context (`context/collector.py`) -2. Recall memory via phase-memory ports (`memory/__init__.py`) -3. Classify risk (`safety/risk.py`) — rule-based; memory signals add caution only -4. Call LLM via `LLMAdapter` Protocol (`llm/adapter.py`) — FakeLLMAdapter today -5. Render explainable response (Rich) - -**Memory (Profile 0 + Profile 1 spike):** -- User-controlled local JSON behind explicit ports (`remember`, `recall`, `forget`, `export`) -- Kinds: `preference`, `retrospection`, `interaction_goal`, `reflection` -- Directory/project-bound activation via `activation_context` -- `cya retrospect` feeds higher-order memory; optional verbal lesson capture (Profile 1) - -**Boundaries:** See `repo-boundary.md`. No production path bypasses the adapter or memory ports. + ## Quick Reference -- Memory contract: `MemoryVision.md` -- Activation/retrospection concept: `docs/cya-memory-activation-and-retrospection-concept.md` -- phase-memory feedback: `docs/phase-memory-optimization-suggestions.md` -- `~/state-hub/mcp_server/TOOLS.md` — MCP tool reference \ No newline at end of file +`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference diff --git a/.claude/rules/credential-routing.md b/.claude/rules/credential-routing.md index 143fe7b..de79ab8 100644 --- a/.claude/rules/credential-routing.md +++ b/.claude/rules/credential-routing.md @@ -1,8 +1,5 @@ # Credential and access routing -> Fleet template mirrored in `AGENTS.md` (Credential and access routing section). -> Re-sync both from `~/ops-warden/wiki/CredentialRouting.md` when the catalog changes. - **Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect** for inference. Run this check **before** requesting secrets, API keys, SSH access, login tokens, or database passwords — in any repo, not only `ops-warden`. @@ -28,14 +25,13 @@ Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run wa ### Quick routing table -Prefer `warden route find` for repo-specific needs. Common routes: - | I need… | Owner | ops-warden executes? | | --- | --- | --- | | SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` | | API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only | | Login / OIDC / MFA | key-cape / Keycloak | No — route only | | Authorization decision | flex-auth | No — route only | +| activity-core → issue-core emission | activity-core + issue-core | No — `warden route show activity-core-issue-sink` | | SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only | ### Anti-patterns (do not do these) diff --git a/.claude/rules/first-session.md b/.claude/rules/first-session.md index 67fa109..882f76f 100644 --- a/.claude/rules/first-session.md +++ b/.claude/rules/first-session.md @@ -1,18 +1,19 @@ ## First Session Protocol -Triggered when `get_domain_summary("capabilities")` shows **no workstreams**. +Triggered when `get_domain_summary("agents")` shows **no workstreams**. The project is registered but work has not yet been structured. **Step 1 — Read, don't write** -- `INTENT.md`, `README.md`, `SCOPE.md`, `AGENTS.md`, `MemoryVision.md` -- Scan repo root: `src/cya/`, `workplans/`, `tests/` +- `~/the-custodian/canon/projects/agents/project_charter_v0.1.md` — purpose, scope +- `~/the-custodian/canon/projects/agents/roadmap_v0.1.md` — planned phases +- Scan repo root: README, directory structure, existing code or docs **Step 2 — Survey in-progress work** Look for TODOs, open branches, half-finished files. Note done vs. started but incomplete. **Step 3 — Propose workstreams to Bernd** -Propose 1–3 workstreams — each a coherent strand, weeks to months, anchored to -INTENT/SCOPE. **Wait for approval before creating.** +Propose 1–3 workstreams — each a coherent strand, weeks to months, anchored to a +roadmap phase. **Wait for approval before creating.** **Step 4 — Create workplan file first, then DB record (ADR-001)** ``` @@ -27,11 +28,11 @@ create_task(workstream_id="", title="...", priority="high|medium|low") **Step 5 — Record the setup** ``` add_progress_event( - summary="First session: structured capabilities/can-you-assist into N workstreams, M tasks", + summary="First session: structured agents into N workstreams, M tasks", event_type="milestone", topic_id="64418556-3206-457a-ba29-6884b5b12cf3", detail={"workstreams": [...], "tasks_created": M} ) ``` - \ No newline at end of file + diff --git a/.claude/rules/repo-boundary.md b/.claude/rules/repo-boundary.md index db625e5..b435d08 100644 --- a/.claude/rules/repo-boundary.md +++ b/.claude/rules/repo-boundary.md @@ -1,11 +1,8 @@ ## Repo boundary -This repo owns **can-you-assist** (`cya`) only. It does not own: +This repo owns **can-you-assist** only. It does not own: -- LLM provider access, API clients, or model hosting → `llm-connect` -- Durable memory storage, profile planners, graph/event stores, or lifecycle algorithms → `phase-memory` -- Global work tracking, decisions, or cross-repo coordination → State Hub / custodian -- Credential custody (API keys, DB passwords, OIDC) → OpenBao / key-cape / operator paths (route via `warden route`) -- SSH certificate issuance → `ops-warden` (`warden sign` only) - -`cya` integrates via stable seams (`LLMAdapter` Protocol, memory ports). State Hub is non-runtime. \ No newline at end of file + diff --git a/.claude/rules/repo-identity.md b/.claude/rules/repo-identity.md index 2b84645..66ab4cf 100644 --- a/.claude/rules/repo-identity.md +++ b/.claude/rules/repo-identity.md @@ -1,7 +1,5 @@ -**Purpose:** Console-native, backend-agnostic LLM assistant (`cya`) for practical local work from the shell, using user-controlled context, memory, and provider configuration. +**Purpose:** Console-native, backend-agnostic LLM helper for practical local shell, repository, filesystem, and note workflows. -**Domain:** capabilities +**Domain:** agents **Repo slug:** can-you-assist **Topic ID:** 64418556-3206-457a-ba29-6884b5b12cf3 -**Workplan prefix:** CYA-WP- -**Command name:** cya \ No newline at end of file diff --git a/.claude/rules/session-protocol.md b/.claude/rules/session-protocol.md index 912cce1..9ac1724 100644 --- a/.claude/rules/session-protocol.md +++ b/.claude/rules/session-protocol.md @@ -1,6 +1,7 @@ ## Session Protocol -State Hub: http://127.0.0.1:8000 (remote tunnel: http://127.0.0.1:18000) +Dev Hub (State Hub API): http://127.0.0.1:8000 +MCP server name in `~/.claude.json`: `dev-hub` **Step 1 — Orient** @@ -10,12 +11,11 @@ cat .custodian-brief.md ``` Then call the MCP tool for richer cross-domain context when MCP tools are exposed: ``` -get_domain_summary("capabilities") +get_domain_summary("agents") ``` If MCP tools are unavailable in the current agent session, use the REST API: ```bash -curl -s "http://127.0.0.1:8000/workstreams/?topic_id=64418556-3206-457a-ba29-6884b5b12cf3&status=active" \ - | python3 -m json.tool +curl -s "http://127.0.0.1:8000/state/summary" | python3 -m json.tool ``` If the hub is offline: `cd ~/state-hub && make api` @@ -40,11 +40,11 @@ curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ ls workplans/ ``` For each file with `status: ready`, `active`, or `blocked`, note pending -`todo`/`in_progress` tasks. +`wait`/`todo`/`progress` tasks. **Step 4 — Present brief** -1. **Active workstreams** for `capabilities` — title, task counts, blocking decisions +1. **Active workstreams** for `agents` — title, task counts, blocking decisions 2. **Pending tasks** from `workplans/` + any `[repo:can-you-assist]` hub tasks 3. **Goal guidance** — if `goal_guidance` in summary: - `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"* @@ -54,12 +54,7 @@ For each file with `status: ready`, `active`, or `blocked`, note pending If no workstreams: follow First Session Protocol (`first-session.md`). -**During work:** -- Keep changes small and inspectable. -- Treat command execution safety as product behavior: explain destructive commands and require explicit confirmation before suggesting execution. -- Do not commit secrets, API keys, local transcripts, private notes, or hidden memory contents. -- Before requesting API keys, SSH access, login tokens, or database passwords, run `warden route find` / `warden route show` per `credential-routing.md`. -- `record_decision()` · `add_progress_event()` · `resolve_decision()` +**During work:** `record_decision()` · `add_progress_event()` · `resolve_decision()` > State Hub is a *read model*. Bootstrap tools (`create_workstream`, `create_task`) > are First Session Protocol only. Work structure belongs in repo files (ADR-001). @@ -87,4 +82,4 @@ cd ~/state-hub && make fix-consistency-remote REPO=can-you-assist ``` **C-15** (DB task ahead of file) is normal in multi-machine workflows — writeback will sync the file to match DB. **C-16** (repo behind remote) blocks all writes -until you pull — intentional to prevent clobbering remote progress. \ No newline at end of file +until you pull — intentional to prevent clobbering remote progress. diff --git a/.claude/rules/stack-and-commands.md b/.claude/rules/stack-and-commands.md index 9b08c87..dc53ac6 100644 --- a/.claude/rules/stack-and-commands.md +++ b/.claude/rules/stack-and-commands.md @@ -1,38 +1,19 @@ ## Stack -- **Language:** Python 3.11+ -- **CLI:** Typer + Rich -- **Config:** TOML -- **Packaging:** setuptools + setuptools_scm (`src/` layout) -- **Tests:** pytest + +- **Language:** +- **Key deps:** ## Dev Commands ```bash -# Recommended: install latest development code -make dev-install +# TODO: Fill in the standard commands for this repo + +# Install dependencies # Run tests -make test -# or: python3 -m pytest tests/ -q -# Build distribution packages -make dist -make release-prep -make check-dist +# Lint / type check -# Run the assistant -cya "your natural language request here" -cya --help -cya --explain-context "show me what context would be collected" -cya retrospect - -# Version / inspection -make version -git status --short -rg --files +# Build / package (if applicable) ``` - -Current memory baseline: **Profile 0** (local JSON + activation + retrospection). -Profile 1 verbal reflections shipped as a minimal spike (CYA-WP-0005); production -hardening tracked in CYA-WP-0006. \ No newline at end of file diff --git a/.claude/rules/workplan-convention.md b/.claude/rules/workplan-convention.md index ec39f03..fb8f266 100644 --- a/.claude/rules/workplan-convention.md +++ b/.claude/rules/workplan-convention.md @@ -25,4 +25,16 @@ Ecosystem todos from other agents arrive as `[repo:can-you-assist]` hub tasks visible at session start. Pick one up by creating the workplan file, then registering the workstream. - \ No newline at end of file +Task blocks use this shape: + +```task +id: CYA-WP-NNNN-T01 +status: wait | todo | progress | done | cancel +priority: high | medium | low +state_hub_task_id: "" # written by fix-consistency — do not edit +``` + +Status progression is `todo` → `progress` → `done`; use `wait` for waiting or +blocked work and `cancel` for stopped work. + + diff --git a/AGENTS.md b/AGENTS.md index 5849bf9..457e702 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,228 +1,108 @@ -# can-you-assist - Agent Instructions - -## Worker Role - -Primary worker agent: Grok Build / Grok Code. - -Run from the repository root. When available, start with `grok inspect` to -confirm Grok has discovered this `AGENTS.md`, the repo files, and any local -`.grok/` configuration. The xAI Build docs say Grok reads the `AGENTS.md` -instruction-file family and can inspect discovered instructions, skills, -plugins, hooks, and MCPs: - -- https://docs.x.ai/build/overview -- https://docs.x.ai/build/features/skills-plugins-marketplaces - -This file is the canonical worker guide for this repo. Do not assume a Claude -Code MCP server is available; use the State Hub HTTP API unless the operator -explicitly provides another integration. +# can-you-assist — Agent Instructions ## Repo Identity -**Purpose:** Console-native, backend-agnostic LLM assistant for practical local -work from the shell, using user-controlled context, memory, and provider -configuration. +**Purpose:** Console-native, backend-agnostic LLM helper for practical local shell, repository, filesystem, and note workflows. -**Domain:** capabilities +**Domain:** agents **Repo slug:** can-you-assist **Topic ID:** `64418556-3206-457a-ba29-6884b5b12cf3` **Workplan prefix:** `CYA-WP-` -**Command name:** `cya` -## Product Direction - -`cya` should help users express intent in natural language from a terminal and -receive useful, explainable help for command-line tasks. It should be good at -repository inspection, file and note workflows, command suggestion, command -explanation, and local context summarization. - -Keep these boundaries crisp: - -- `can-you-assist` owns the CLI assistant experience, local context gathering, - safety prompts, command explanations, and orchestration of assistance. -- `llm-connect` owns provider/backend access. Do not hard-code one LLM vendor - as the conceptual foundation. -- `phase-memory` owns user-controlled memory, preferences, history, and - adaptation. Do not hide memory in opaque hosted state. -- State Hub tracks work, coordination, progress, and cross-repo handoffs. It - should not become a runtime dependency of the `cya` CLI. +--- ## State Hub Integration -The Custodian State Hub tracks work across all domains. Interact via HTTP REST. +The Custodian State Hub tracks work across all domains. Interact via HTTP REST — +there is no MCP server for Codex agents. | Context | URL | |---------|-----| | Local workstation | `http://127.0.0.1:8000` | | Remote via tunnel | `http://127.0.0.1:18000` | -### Orient At Session Start +### Orient at session start ```bash -# Offline brief - generated by State Hub consistency tooling when available +# Offline brief — works without hub connection cat .custodian-brief.md -# Active workstreams for this domain/topic +# Active workstreams for this domain curl -s "http://127.0.0.1:8000/workstreams/?topic_id=64418556-3206-457a-ba29-6884b5b12cf3&status=active" \ | python3 -m json.tool -# Inbox for this repo worker +# Check inbox curl -s "http://127.0.0.1:8000/messages/?to_agent=can-you-assist&unread_only=true" \ | python3 -m json.tool ``` Mark a message read: - ```bash curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ -H "Content-Type: application/json" -d '{}' ``` -### Update Task Status - -```bash -curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ - -H "Content-Type: application/json" \ - -d '{"status": "in_progress"}' -``` - -Allowed task statuses: `todo`, `in_progress`, `done`, `blocked`. - -### Log Progress - -Log progress at session close and after meaningful milestones: +### Log progress (required at session close) ```bash curl -s -X POST http://127.0.0.1:8000/progress/ \ -H "Content-Type: application/json" \ -d '{ - "summary": "what changed", + "summary": "what was done", "event_type": "note", - "author": "grok", + "author": "codex", "workstream_id": "", "task_id": "" }' ``` -Omit `workstream_id` and `task_id` only when there is no applicable item. +Omit `workstream_id` / `task_id` when not applicable. + +### Update task status + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"status": "progress"}' +# values: wait | todo | progress | done | cancel +``` + +### Flag a task for human review + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"needs_human": true, "intervention_note": "reason"}' +``` + +--- ## Session Protocol -Start: +**Start:** +1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe) +2. Check inbox: `GET /messages/?to_agent=can-you-assist&unread_only=true`; mark read +3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks +4. Check human-needed tasks: `GET /tasks/?needs_human=true` -1. Run `git status --short`. -2. Read `.custodian-brief.md` if present; if absent, use the State Hub API - queries above. -3. Check the `can-you-assist` inbox and mark read only after acting on a - message or carrying it forward in a workplan. -4. Scan `workplans/` if it exists. If it does not exist yet, the onboarding - workstream should create it. -5. Pick the highest-priority active task that is unblocked and update task - status before substantial work. +**During work:** +- Update task statuses in workplan files as tasks progress +- Record significant decisions via `POST /decisions/` -During work: - -- Keep changes small and inspectable. -- Treat command execution safety as product behavior: explain destructive or - broad filesystem commands and require explicit confirmation before suggesting - execution. -- Before requesting API keys, SSH access, login tokens, or database passwords, - run `warden route find` / `warden route show` per **Credential and access routing**. -- Do not commit secrets, API keys, local transcripts, private notes, or hidden - memory contents. -- Preserve user-controlled memory as a design principle. Prefer explicit, - inspectable local files over hidden state. -- Record significant design decisions with `POST /decisions/`. - -Close: - -1. Update workplan task statuses to match reality. -2. Log a progress event in State Hub. -3. Ask the custodian operator to run: - -```bash -cd ~/state-hub && make fix-consistency REPO=can-you-assist -``` - -That syncs repo workplan files into the State Hub DB and regenerates -`.custodian-brief.md`. - -## Current Grok Handoff - -State Hub registration has been created for `can-you-assist` under the -`capabilities` domain. Look for active workstream -`repo-integration-can-you-assist`. - -First useful worker moves: - -1. Read `INTENT.md`, `README.md`, this `AGENTS.md`, and `SCOPE.md`. -2. Create `workplans/CYA-WP-0001-console-native-mvp.md` with a focused first - implementation slice: CLI skeleton, safe command-assistance flow, - llm-connect adapter boundary, phase-memory boundary, and test strategy. -3. Keep the first workplan `ready` until the repo state and stack choice are - reviewed. Move it to `active` when implementation begins. -4. Run or request SBOM ingest from State Hub after the first dependency files - exist. -5. Register obvious extension points and technical debt once there is code to - anchor them. - -## Commands - -```bash -# === Packaging & Installation (CYA-WP-0004) === - -# Recommended: Stay on latest development code -make dev-install - -# Build distribution packages (sdist + wheel) -make dist - -# Prepare a release (tests + clean build) -make release-prep - -# Verify a built wheel in isolation -make check-dist - -# Run the assistant -cya "your natural language request here" -cya --offline "..." # deterministic fake adapter (CI / no API keys) -cya --help -cya --explain-context "show me what context would be collected" - -# Memory features (0003 + 0005) -cya retrospect # Guided reflection session -# Memory: Profile 0 baseline + production Profile 1 (CYA-WP-0006). -# Profiles 2–3 (hierarchical synthesis, procedural rules) remain roadmap — see MemoryVision.md. - -# Tests -python -m pytest tests/ -q - -# Git / inspection -git status --short -git log --oneline -5 -rg --files -``` - -No formal lint or build system yet (ruff is configured in pyproject.toml but not enforced in CI for the first slice). Add `make test` / `make lint` targets in a follow-on when needed. - -Current primary entry point: `cya` (after editable install). - -Relevant workplans: -- `workplans/CYA-WP-0002-memory-integration-roadmap.md` -- `workplans/CYA-WP-0003-contextual-memory-activation-and-retrospection.md` -- `workplans/CYA-WP-0004-dev-install-and-release-packaging.md` -- `workplans/CYA-WP-0005-agentic-memory-profiles-and-phase-memory-feedback.md` -- `workplans/CYA-WP-0006-profile-1-production-hardening.md` (finished) -- `workplans/CYA-WP-0007-interactive-shell-session.md` (ready — interactive REPL + history + hub) -- `workplans/CYA-WP-0008-llm-connect-adapter-integration.md` (finished — real LLM behind adapter seam) +**Close:** +1. Update workplan file task statuses to reflect progress +2. Log: `POST /progress/` with a summary of what changed +3. Note for the custodian operator: after workplan file changes, run from + `~/state-hub`: + ```bash + make fix-consistency REPO=can-you-assist + ``` + This syncs task status from files into the hub DB. --- ## Credential and access routing -> Fleet template mirrored in `.claude/rules/credential-routing.md` for Claude Code. -> Re-sync both from `~/ops-warden/wiki/CredentialRouting.md` when the catalog changes. - **Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect** for inference. Run this check **before** requesting secrets, API keys, SSH access, login tokens, or database passwords — in any repo, not only `ops-warden`. @@ -248,14 +128,13 @@ Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run wa ### Quick routing table -Prefer `warden route find` for repo-specific needs. Common routes: - | I need… | Owner | ops-warden executes? | | --- | --- | --- | | SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` | | API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only | | Login / OIDC / MFA | key-cape / Keycloak | No — route only | | Authorization decision | flex-auth | No — route only | +| activity-core → issue-core emission | activity-core + issue-core | No — `warden route show activity-core-issue-sink` | | SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only | ### Anti-patterns (do not do these) @@ -273,52 +152,68 @@ get wrong. **Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml` + + + --- -## Workplan Convention +## Workplan Convention (ADR-001) -Work items originate as files in this repo. The hub is a read/cache/index -layer that rebuilds from files. +Work items originate as files in this repo — not in the hub. The hub is a +read/cache/index layer that rebuilds from files. -**File location:** `workplans/CYA-WP-NNNN-.md` +**File location:** `workplans/CAN-WP-NNNN-.md` -**Archived location:** `workplans/archived/YYMMDD-CYA-WP-NNNN-.md` +**Archived location:** finished workplans may move to +`workplans/archived/YYMMDD-CAN-WP-NNNN-.md`. The `YYMMDD` prefix is +the completion/archive date; the frontmatter `id` does not change. -**Ad hoc tasks:** small opportunistic fixes may use -`workplans/ADHOC-YYYY-MM-DD.md` with task ids like -`ADHOC-YYYY-MM-DD-T01`. Use this only for low-risk work completed directly. +**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use +`workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use +this only for low-risk work completed directly; create a normal workplan for +anything needing analysis, design, approval, dependencies, or multiple phases. -Frontmatter: +**Frontmatter:** ```yaml --- -id: CYA-WP-NNNN +id: CAN-WP-NNNN type: workplan title: "..." -domain: capabilities +domain: agents repo: can-you-assist status: proposed | ready | active | blocked | backlog | finished | archived -owner: grok -topic_slug: foerster-capabilities +owner: codex +topic_slug: ... created: "YYYY-MM-DD" updated: "YYYY-MM-DD" -state_hub_workstream_id: "" # written by fix-consistency - do not edit +state_hub_workstream_id: "" # written by fix-consistency — do not edit --- ``` -Task block format: +Use `proposed` for a new draft, `ready` after review against current repo +state, and `finished` after implementation. `stalled` and `needs_review` are +derived health labels, not frontmatter statuses. -```` +**Task block format** (one per `##` section): + +``` ## Task Title -```task -id: CYA-WP-NNNN-T01 -status: todo | in_progress | done | blocked +` ` `task +id: CAN-WP-NNNN-T01 +status: wait | todo | progress | done | cancel priority: high | medium | low -state_hub_task_id: "" # written by fix-consistency - do not edit -``` +state_hub_task_id: "" # written by fix-consistency — do not edit +` ` ` Task description text. -```` +``` -Status progression: `todo` -> `in_progress` -> `done` or `blocked`. +Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work. + +To create a new workplan: +1. Write the file following the format above +2. Notify the custodian operator to run `make fix-consistency REPO=can-you-assist` + (or send a message to the hub agent via `POST /messages/`) diff --git a/CLAUDE.md b/CLAUDE.md index 6e5d2c0..5f80ed9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,4 +9,4 @@ @.claude/rules/architecture.md @.claude/rules/repo-boundary.md @.claude/rules/credential-routing.md -@.claude/rules/agents.md \ No newline at end of file +@.claude/rules/agents.md diff --git a/workplans/CYA-WP-0001-console-native-mvp.md b/workplans/CYA-WP-0001-console-native-mvp.md index dae17af..618d63e 100644 --- a/workplans/CYA-WP-0001-console-native-mvp.md +++ b/workplans/CYA-WP-0001-console-native-mvp.md @@ -2,7 +2,7 @@ id: CYA-WP-0001 type: workplan title: "Console-Native MVP: CLI Skeleton, Safe Assistance Flow, and Integration Boundaries" -domain: capabilities +domain: agents repo: can-you-assist status: finished owner: grok diff --git a/workplans/CYA-WP-0002-memory-integration-roadmap.md b/workplans/CYA-WP-0002-memory-integration-roadmap.md index ba3cf1b..ffea203 100644 --- a/workplans/CYA-WP-0002-memory-integration-roadmap.md +++ b/workplans/CYA-WP-0002-memory-integration-roadmap.md @@ -2,7 +2,7 @@ id: CYA-WP-0002 type: workplan title: "Memory Integration Roadmap: From Thin Ports to Profile-Driven phase-memory Backing" -domain: capabilities +domain: agents repo: can-you-assist status: done owner: grok diff --git a/workplans/CYA-WP-0003-contextual-memory-activation-and-retrospection.md b/workplans/CYA-WP-0003-contextual-memory-activation-and-retrospection.md index 0cf0d9c..dd86904 100644 --- a/workplans/CYA-WP-0003-contextual-memory-activation-and-retrospection.md +++ b/workplans/CYA-WP-0003-contextual-memory-activation-and-retrospection.md @@ -2,7 +2,7 @@ id: CYA-WP-0003 type: workplan title: "Contextual Memory Activation and Retrospection Loops for Continuous Optimization" -domain: capabilities +domain: agents repo: can-you-assist status: done owner: grok diff --git a/workplans/CYA-WP-0004-dev-install-and-release-packaging.md b/workplans/CYA-WP-0004-dev-install-and-release-packaging.md index aeb26c7..a3f3826 100644 --- a/workplans/CYA-WP-0004-dev-install-and-release-packaging.md +++ b/workplans/CYA-WP-0004-dev-install-and-release-packaging.md @@ -2,7 +2,7 @@ id: CYA-WP-0004 type: workplan title: "Developer Installation from Git and Release Distribution Packaging" -domain: capabilities +domain: agents repo: can-you-assist status: done owner: grok diff --git a/workplans/CYA-WP-0005-agentic-memory-profiles-and-phase-memory-feedback.md b/workplans/CYA-WP-0005-agentic-memory-profiles-and-phase-memory-feedback.md index eacd62f..0d290b8 100644 --- a/workplans/CYA-WP-0005-agentic-memory-profiles-and-phase-memory-feedback.md +++ b/workplans/CYA-WP-0005-agentic-memory-profiles-and-phase-memory-feedback.md @@ -2,7 +2,7 @@ id: CYA-WP-0005 type: workplan title: "Agentic Memory Profiles (0–3) and phase-memory Interface Optimization" -domain: capabilities +domain: agents repo: can-you-assist status: done owner: grok diff --git a/workplans/CYA-WP-0006-profile-1-production-hardening.md b/workplans/CYA-WP-0006-profile-1-production-hardening.md index 7569e6e..43796ff 100644 --- a/workplans/CYA-WP-0006-profile-1-production-hardening.md +++ b/workplans/CYA-WP-0006-profile-1-production-hardening.md @@ -2,7 +2,7 @@ id: CYA-WP-0006 type: workplan title: "Profile 1 Production Hardening: Reflection UX, Compaction, and Surfacing" -domain: capabilities +domain: agents repo: can-you-assist status: finished owner: grok diff --git a/workplans/CYA-WP-0007-interactive-shell-session.md b/workplans/CYA-WP-0007-interactive-shell-session.md index b5d04df..9cbe9c3 100644 --- a/workplans/CYA-WP-0007-interactive-shell-session.md +++ b/workplans/CYA-WP-0007-interactive-shell-session.md @@ -2,7 +2,7 @@ id: CYA-WP-0007 type: workplan title: "Interactive Shell Session: REPL, History Context, and Hub-Aware Dev-Sec-Ops Helper" -domain: capabilities +domain: agents repo: can-you-assist status: ready owner: grok diff --git a/workplans/CYA-WP-0008-llm-connect-adapter-integration.md b/workplans/CYA-WP-0008-llm-connect-adapter-integration.md index 5c8f3b8..0ca140d 100644 --- a/workplans/CYA-WP-0008-llm-connect-adapter-integration.md +++ b/workplans/CYA-WP-0008-llm-connect-adapter-integration.md @@ -2,7 +2,7 @@ id: CYA-WP-0008 type: workplan title: "llm-connect Adapter Integration for Production Assistance" -domain: capabilities +domain: agents repo: can-you-assist status: finished owner: grok