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-0004 Packaging & Distribution Slice)

Four implementation slices have been delivered:

• CYA-WP-0001 (Console-Native MVP): Core CLI, bounded context collection, rule-based safety with mandatory confirmation, LLMAdapter Protocol seam, basic orchestrator.
• CYA-WP-0002 (Memory Integration): Real user-controlled, persisting memory (scoped JSON) behind explicit ports, wired into context and safety.
• CYA-WP-0003 (Contextual Activation & Retrospection): Directory/project-bound automatic memory activation, cya retrospect guided reflection sessions, retrospection outcomes feeding future behavior (continuous user-driven optimization loop).
• Profile 0 baseline (post-0003, formalized in CYA-WP-0005 T02): The current shipped memory implementation (local JSON + kinds + activation_context + provenance + retrospection helper) is now explicitly documented as Profile 0 — the stable, high-quality foundation for future self-improving profiles 1–3. See MemoryVision.md for the full baseline description.
• CYA-WP-0005 (Agentic Memory Profiles + first self-improvement capability): Complete profile model (Profile 0 baseline + detailed definitions + integration plans + Capability Matrix for Profiles 1–3) plus a minimal but fully working Profile 1 (Reflexion-style verbal reflections/lessons) spike: remember_reflection() + KIND_REFLECTION, optional "capture verbal lesson" step inside cya retrospect, preferential activation when reflections are present, and surfacing in responses / --explain-context. The sister-repo optimization suggestions document for phase-memory was also finalized. See the workplan, MemoryVision.md, and docs/phase-memory-optimization-suggestions.md.
• CYA-WP-0004 (Dev-Head Install & Release Packaging): Reliable installation from development head (make dev-install, direct git+ installs), dynamic versioning via setuptools_scm, clean distribution package building (python -m build + verification), lightweight release process, and supporting documentation/Makefile.

Core capabilities now include:

• Natural language request handling via clean Typer CLI.
• Bounded, transparent local context collection.
• Genuine rule-based (memory-aware) risk classification with mandatory confirmation.
• Stable LLMAdapter Protocol.
• Real, user-controlled, contextually activated memory (Profile 0: directory/project scoped local JSON with kinds, activation_context, provenance, and retrospection outcomes as higher-order memory).
• Automatic memory activation based on working directory/git root.
• cya retrospect for structured reflection and goal setting, now with optional verbal lesson capture (first delivered Profile 1 self-improvement behavior).
• Full developer workflow: dev-head install, testing, building distribution packages, and a documented release process.
• Transparent, inspectable behavior via --explain-context.

All LLM interaction flows through the documented adapter seam. Memory flows through explicit ports. Packaging and distribution are now first-class concerns with a clear path forward. No production path bypasses the defined 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).
• Production PyPI publishing and automated release CI (documented process and local tooling exist; actual publication is future work).
• 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, profiles, and activation planning	Explicit ports with real (local JSON + contextual activation + retrospection) implementation; long-term target is deeper profile-driven integration
State Hub	Work tracking, decisions, coordination	HTTP REST (non-runtime)

Current Delivered Scope (Post CYA-WP-0005 T05)

Significant slices have been delivered beyond the original MVP (most recently the full profile model and first self-improving capability from CYA-WP-0005):

• Full console-native CLI with rich output.
• Context-aware, directory/project-bound memory activation.
• User-driven retrospection and continuous optimization loops (cya retrospect).
• Real, inspectable, user-controlled memory with strong explainability and safety integration.
• Complete developer workflow: installation from dev head, testing, building distribution packages, and a documented release process.
• Packaging and distribution now treated as first-class concerns (with registered future work).

See the individual workplans for detailed scope per slice.

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 with contextual activation; deeper integration is planned future work per MemoryVision.md).
• Real llm-connect client implementation (only the stable LLMAdapter Protocol contract + FakeLLMAdapter exists).
• Deep semantic repository understanding or large-scale content analysis.
• Automatic command execution (even "safe" suggestions) — explicit user confirmation remains mandatory for anything non-safe.
• Rich multi-turn conversational state beyond lightweight scoped memory + retrospection.
• Cost tracking, token budgeting, or usage dashboards.
• Team/shared memory or collaboration features.
• Plugin system or domain-specific extensions.
• Production PyPI publishing and fully automated release CI (a lightweight documented local process exists; automation is future work).

Extension Points (Registered)

• cya/llm/adapter.py — LLMAdapter Protocol (the primary seam).
• cya/memory/__init__.py — the explicit ports (with real implementation, contextual activation, and retrospection support).
• cya/safety/risk.py — the _RULES table and classify() function (memory-aware).
• cya/context/collector.py — collection functions and ignore policy.
• cya/orchestrator.py — the main coordination entry point.
• Packaging & distribution: Makefile, pyproject.toml, docs/release-process.md, and MANIFEST.in (first-class concern with registered future work).

Success Criteria (Current State)

A new user or contributor can:

• Install the latest development code easily (make dev-install or direct git+) and use cya for realistic tasks after reading the README.
• Understand exactly what context and memory influenced a response via --explain-context.
• Trust that dangerous actions will never execute without explicit confirmation.
• Use cya retrospect to reflect on usage and set goals that influence future behavior.
• Build and verify distribution packages locally.
• See a clear path for how real llm-connect, deeper phase-memory, and future PyPI releases will integrate.

Sibling project owners (llm-connect, phase-memory, State Hub) can read the workplans + boundary documentation and know precisely where their packages integrate.

---

This SCOPE document reflects the state after CYA-WP-0004 (Dev-Head Install & Release Packaging).

It remains intentionally narrower than the long-term vision in INTENT.md and MemoryVision.md, but now incorporates significant advances in contextual memory activation, user-driven retrospection/optimization loops, and proper packaging & distribution capabilities.

See the individual workplans (especially CYA-WP-0003 and CYA-WP-0004) and MemoryVision.md for the intended direction of deeper phase-memory integration and future evolution.