diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..194c585 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,230 @@ +# 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. + +## Repo Identity + +**Purpose:** Console-native, backend-agnostic LLM assistant for practical local +work from the shell, using user-controlled context, memory, and provider +configuration. + +**Domain:** capabilities +**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. + +| Context | URL | +|---------|-----| +| Local workstation | `http://127.0.0.1:8000` | +| Remote via tunnel | `http://127.0.0.1:18000` | + +### Orient At Session Start + +```bash +# Offline brief - generated by State Hub consistency tooling when available +cat .custodian-brief.md + +# Active workstreams for this domain/topic +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 +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: + +```bash +curl -s -X POST http://127.0.0.1:8000/progress/ \ + -H "Content-Type: application/json" \ + -d '{ + "summary": "what changed", + "event_type": "note", + "author": "grok", + "workstream_id": "", + "task_id": "" + }' +``` + +Omit `workstream_id` and `task_id` only when there is no applicable item. + +## Session Protocol + +Start: + +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: + +- 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. +- 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 + +The repo is currently an intent/document seed. There is no build or test +system yet. + +Useful inspection commands: + +```bash +rg --files +sed -n '1,240p' INTENT.md +git status --short +git log --oneline -5 +``` + +When implementation starts, update this section with the package manager, +build, test, lint, and local run commands. + +## Workplan Convention + +Work items originate as files in this repo. The hub is a read/cache/index +layer that rebuilds from files. + +**File location:** `workplans/CYA-WP-NNNN-.md` + +**Archived location:** `workplans/archived/YYMMDD-CYA-WP-NNNN-.md` + +**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. + +Frontmatter: + +```yaml +--- +id: CYA-WP-NNNN +type: workplan +title: "..." +domain: capabilities +repo: can-you-assist +status: proposed | ready | active | blocked | backlog | finished | archived +owner: grok +topic_slug: foerster-capabilities +created: "YYYY-MM-DD" +updated: "YYYY-MM-DD" +state_hub_workstream_id: "" # written by fix-consistency - do not edit +--- +``` + +Task block format: + +```` +## Task Title + +```task +id: CYA-WP-NNNN-T01 +status: todo | in_progress | done | blocked +priority: high | medium | low +state_hub_task_id: "" # written by fix-consistency - do not edit +``` + +Task description text. +```` + +Status progression: `todo` -> `in_progress` -> `done` or `blocked`. diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..1f8f2e3 --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,46 @@ +# Scope: can-you-assist + +## Purpose + +`can-you-assist` provides `cya`, a console-native LLM helper for practical +local work. It lets a terminal user ask for help in natural language, gather +relevant local context intentionally, and receive safe, explainable assistance +for command-line, repository, filesystem, note, and text workflows. + +## Owns + +- The `cya` command-line user experience. +- Intent parsing and task framing for local shell work. +- Local context collection from the current directory, selected files, stdin, + git state, logs, notes, and user-provided paths. +- Safe command suggestion and explanation workflows. +- Prompt/request orchestration against `llm-connect`. +- Local preference and memory usage through `phase-memory`. +- Transparent configuration and inspectable local state for this assistant. + +## Does Not Own + +- Provider-specific LLM clients or vendor credentials; that belongs in + `llm-connect`. +- Long-term memory storage semantics; that belongs in `phase-memory`. +- Global State Hub implementation or workstream indexing. +- Autonomous shell execution without clear user confirmation. +- Hidden, vendor-owned personalization or opaque memory. + +## Integrates With + +- `llm-connect` for backend-agnostic model access. +- `phase-memory` for user-controlled history, preferences, and adaptation. +- State Hub for work tracking, repo coordination, progress, and decisions. + +## Initial Direction + +The first implementation slice should establish a minimal but real CLI: + +- parse a natural-language request; +- inspect current working-directory context safely; +- produce an explainable command or answer; +- route LLM calls through an adapter boundary shaped for `llm-connect`; +- leave memory hooks explicit but thin until `phase-memory` integration is + ready; +- include tests around command-suggestion safety and context selection.