generated from coulomb/repo-seed
tegwick
f93b766e12
- New MemoryVision.md outlining long-term vision for phase-memory integration in cya (profiles, phases, lifecycle, ports) - Persisted full Intent-vs-Scope gap analysis in history/ - Updated SCOPE.md to reflect post-MVP reality and MemoryVision direction - Minor cross-references in AGENTS.md and the CYA-WP-0001 workplan This lays the foundation for the next workplan (CYA-WP-0002) focused on realizing the MemoryVision. Refs: MemoryVision.md, history/2026-05-26-CYA-Intent-Scope-Gap-Analysis.md, CYA-WP-0001 T05/T08
99 lines
5.4 KiB
Markdown
99 lines
5.4 KiB
Markdown
# Scope: can-you-assist
|
||
|
||
## Purpose
|
||
|
||
`can-you-assist` provides the `cya` command — a console-native, backend-agnostic LLM assistant for practical local work.
|
||
|
||
It allows users to express intent in natural language from the terminal and receive safe, explainable, context-aware assistance while keeping memory, history, preferences, and adaptation under explicit user control.
|
||
|
||
## Current Status (Post MVP Slice)
|
||
|
||
The first narrow implementation slice (CYA-WP-0001) has been delivered. A working `cya` tool now exists that can be installed with `pip install -e .`.
|
||
|
||
Core capabilities implemented:
|
||
- Natural language request handling via a clean Typer CLI.
|
||
- Bounded, transparent, non-recursive local context collection (cwd + git + environment + explicit files).
|
||
- Genuine rule-based risk classification with mandatory terminal confirmation for anything above "safe".
|
||
- Stable `LLMAdapter` Protocol boundary (currently satisfied by a deterministic `FakeLLMAdapter`).
|
||
- Strictly minimal explicit no-op ports for future `phase-memory` integration.
|
||
- A small orchestrator that coordinates the above.
|
||
|
||
All LLM interaction flows through the documented adapter seam. No production path bypasses it.
|
||
|
||
## Owns
|
||
|
||
- The `cya` command-line user experience and argument parsing.
|
||
- Intent framing and high-level task classification for console work.
|
||
- Local context collection (current directory, git state, selected files, stdin, minimal environment facts).
|
||
- Safety layer: rule-based risk assessment + mandatory explicit confirmation flow.
|
||
- Orchestration of the request → context → safety → LLM adapter → response pipeline.
|
||
- The stable `LLMAdapter` Protocol and the contract for how `cya` talks to LLM backends.
|
||
- Explicit, minimal integration points (ports) for `phase-memory`.
|
||
- Transparent, inspectable behavior (especially via `--explain-context`).
|
||
- User-facing documentation, examples, and safety guarantees for the CLI tool.
|
||
|
||
## Does Not Own
|
||
|
||
- Any specific LLM provider, API client, or model hosting (belongs to `llm-connect`).
|
||
- Durable memory storage, preference models, history semantics, or adaptation algorithms (belongs to `phase-memory`).
|
||
- Global work tracking, decisions, or cross-repo coordination (belongs to State Hub / custodian).
|
||
- Autonomous or background execution of commands without explicit user confirmation.
|
||
- Deep repository indexing, embeddings, or large-scale content analysis (explicit non-goal of the first slice).
|
||
- Voice, speech, phone-bridge, or non-terminal interfaces (future work).
|
||
- Packaging, distribution, or multi-platform installers beyond basic editable install.
|
||
- Long-lived conversational REPL or session state (one-shot + very lightweight session only).
|
||
|
||
## Integrates With
|
||
|
||
| Project | Responsibility | Integration Style |
|
||
|---------------|-----------------------------------------|------------------------------------|
|
||
| `llm-connect` | Provider access, config, token counting, structured responses | Stable `LLMAdapter` Protocol |
|
||
| `phase-memory`| User-controlled memory, preferences, history | Explicit thin ports (currently no-op) |
|
||
| State Hub | Work tracking, decisions, coordination | HTTP REST (non-runtime) |
|
||
|
||
## MVP Scope (CYA-WP-0001)
|
||
|
||
What was explicitly in scope for the first slice:
|
||
|
||
- A functional `cya` CLI that accepts natural language requests.
|
||
- Safe, bounded context collection with full transparency (`--explain-context`).
|
||
- Rule-based safety classification as the primary mechanism, with mandatory confirmation.
|
||
- A clean, documented adapter boundary for future real LLM backends.
|
||
- Strictly minimal memory ports (no hidden state, no local JSON store).
|
||
- Basic orchestrator that ties the pieces together.
|
||
- Test coverage focused on safety invariants and context rules.
|
||
- Clear public boundaries and extension points.
|
||
|
||
## Explicitly Out of Scope (MVP and Near-Term)
|
||
|
||
- Any durable or sophisticated memory implementation.
|
||
- Real `llm-connect` client (only the contract + fake exists).
|
||
- Deep git/repository understanding beyond basic status + log.
|
||
- Automatic command execution (even "safe" suggestions).
|
||
- Structured editing / patch generation.
|
||
- Multi-turn conversation state.
|
||
- Cost tracking, token budgeting, or usage dashboards.
|
||
- Team/shared memory or collaboration features.
|
||
- Plugin system or domain-specific extensions.
|
||
|
||
## Extension Points (Registered)
|
||
|
||
- `cya/llm/adapter.py` — `LLMAdapter` Protocol (the primary seam).
|
||
- `cya/memory/__init__.py` — the four explicit ports (`remember_preference`, `recall_preferences`, `forget`, `export_memory`).
|
||
- `cya/safety/risk.py` — the `_RULES` table and `classify()` function.
|
||
- `cya/context/collector.py` — collection functions and ignore policy.
|
||
- `cya/orchestrator.py` — the main coordination entry point.
|
||
|
||
## Success Criteria (Current Slice)
|
||
|
||
A new user can:
|
||
- Clone the repo, run `pip install -e .`, and successfully use `cya` for 2–3 realistic tasks after reading only the README.
|
||
- Understand exactly what context is being sent via `--explain-context`.
|
||
- Trust that dangerous actions will never execute without explicit confirmation.
|
||
- See a clear path for how real `llm-connect` and `phase-memory` will plug in later.
|
||
|
||
Sibling project owners can read the workplan + boundary documentation and know precisely where their packages integrate.
|
||
|
||
---
|
||
|
||
**This SCOPE document reflects the state after the CYA-WP-0001 MVP slice.** It is intentionally narrower than the long-term vision in INTENT.md. |