coulomb/can-you-assist
Archived
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add AGENTS.md and SCOPE.md as canonical repo instructions

Browse Source 
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:
Bernd Worsch
2026-05-26 00:40:52 +02:00
parent 1bdd8e03d8
commit cbf66cf967
2 changed files with 276 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

230
AGENTS.md Normal file
View 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
View 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.