can-you-assist/AGENTS.md

# 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

```bash
# Install (editable, for development)
pip install -e .

# Run the assistant
cya "your natural language request here"
cya --help
cya --explain-context "show me what context would be collected"

# Memory is now real (T02)
# Preferences persist in ~/.config/cya/memory/<scope>.json (user-controlled JSON)
cya "remember that I always want --short --branch on git status"

# Tests (safety + memory)
python -m pytest tests/ -q
# or: pytest tests/ -q

# Git / inspection (always useful)
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).

Memory workplan: `workplans/CYA-WP-0002-memory-integration-roadmap.md`

## 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`.