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

# 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:

curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
  -H "Content-Type: application/json" -d '{}'

Update Task Status

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:

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:

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

# === 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 --help
cya --explain-context "show me what context would be collected"

# Memory features (0003 + 0005)
cya retrospect                    # Guided reflection session
# Current memory implementation is Profile 0 (see CYA-WP-0005 and MemoryVision "Profile 0 Baseline").
# Future Profiles 1–3 (verbal self-improvement, hierarchical synthesis, procedural rules) are tracked in that workplan.

# 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 (current)

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:

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