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 CYA-WP-0002 Memory Slice)

Two implementation slices have been delivered:

• CYA-WP-0001 (Console-Native MVP): Core CLI, context collection, rule-based safety with mandatory confirmation, LLMAdapter seam, and thin memory ports.
• CYA-WP-0002 (Memory Integration): Real user-controlled, persisting memory implementation behind the explicit ports, wired into the orchestrator and --explain-context, memory signals integrated into safety, dedicated tests, and documentation.

Core capabilities now include:

• Natural language request handling via a clean Typer CLI.
• Bounded, transparent, non-recursive local context collection.
• Genuine rule-based risk classification (now memory-aware) with mandatory terminal confirmation.
• Stable LLMAdapter Protocol boundary.
• Real, user-controlled memory for preferences and workflow patterns (scoped JSON backing under ~/.config/cya/memory/, fully inspectable and user-editable).
• Memory surfaced in explanations and fed into safety decisions.
• A small orchestrator coordinating the pipeline.

All LLM interaction flows through the documented adapter seam. Memory flows through explicit ports. No production path bypasses these boundaries.

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, now real (persisting) integration with user-controlled memory via phase-memory ports.
• 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 ports with real (local JSON) implementation (T02); long-term target is deeper profile-driven integration
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.
• Real user-controlled memory implementation (scoped, persisting, explainable) behind the explicit ports, with a clean seam for future deeper phase-memory integration.
• 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 (Current and Near-Term)

• Full deep integration with the complete phase-memory profile/planner/graph system (current implementation uses a deliberate, user-visible local JSON store as the first real backing; deeper integration is planned future work).
• Real llm-connect client (only the contract + fake exists).
• Deep git/repository understanding beyond basic status + log + user-declared memory.
• Automatic command execution (even "safe" suggestions).
• Structured editing / patch generation.
• Rich multi-turn conversational state (one-shot + lightweight scoped memory only).
• 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 with real (persisting, user-controlled) implementation behind them.
• 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 CYA-WP-0001 (MVP) + CYA-WP-0002 (Memory Integration).

It is intentionally narrower than the long-term vision in INTENT.md and MemoryVision.md, but now includes a real first slice of user-controlled memory as delivered by 0002.

See workplans/CYA-WP-0002-memory-integration-roadmap.md and MemoryVision.md for the intended direction of deeper phase-memory integration.