generated from coulomb/repo-seed
docs: add AGENTS.md and SCOPE.md as canonical repo instructions
These were part of the initial Grok handoff for the can-you-assist repo integration workstream (repo-integration-can-you-assist). - AGENTS.md: Worker protocol, State Hub integration, workplan convention, session start/close checklist. - SCOPE.md: Crisp boundaries (owns CLI + orchestration, does not own llm-connect or phase-memory implementations). Complements the just-added CYA-WP-0001 workplan. Brings the documented seed state to a complete, committed baseline. Workstream: 0a1233fd-75ab-4726-8857-6c97de939069
This commit is contained in:
230
AGENTS.md
Normal file
230
AGENTS.md
Normal file
@@ -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/<id>/read" \
|
||||
-H "Content-Type: application/json" -d '{}'
|
||||
```
|
||||
|
||||
### Update Task Status
|
||||
|
||||
```bash
|
||||
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
|
||||
-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": "<uuid>",
|
||||
"task_id": "<uuid>"
|
||||
}'
|
||||
```
|
||||
|
||||
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-<slug>.md`
|
||||
|
||||
**Archived location:** `workplans/archived/YYMMDD-CYA-WP-NNNN-<slug>.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: "<uuid>" # 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: "<uuid>" # written by fix-consistency - do not edit
|
||||
```
|
||||
|
||||
Task description text.
|
||||
````
|
||||
|
||||
Status progression: `todo` -> `in_progress` -> `done` or `blocked`.
|
||||
46
SCOPE.md
Normal file
46
SCOPE.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user