can-you-assist/SCOPE.md

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.