can-you-assist/workplans/CYA-WP-0001-console-native-mvp.md

id, type, title, domain, repo, status, owner, topic_slug, created, updated

id	type	title	domain	repo	status	owner	topic_slug	created	updated
CYA-WP-0001	workplan	Console-Native MVP: CLI Skeleton, Safe Assistance Flow, and Integration Boundaries	capabilities	can-you-assist	ready	grok	foerster-capabilities	2026-05-25	2026-05-25

CYA-WP-0001: Console-Native MVP — CLI Skeleton, Safe Assistance Flow, and Integration Boundaries

Goal

Deliver the first narrow, usable slice of cya (the can-you-assist console assistant) that proves the core loop:

User expresses intent in natural language from a terminal → cya safely gathers minimal relevant local context → routes through a clean adapter boundary for llm-connect → returns an explainable suggestion, command, or answer → enforces explicit confirmation for any potentially destructive or broad action.

This workplan establishes the CLI surface, context collector, safety layer, and the integration seams for the two sibling projects (llm-connect and phase-memory) without taking ownership of their implementations. It produces a minimal but real tool that can be invoked today for practical console work.

Current Evidence

• High-quality intent, scope, and agent instruction documents exist and are consistent (INTENT.md, SCOPE.md, AGENTS.md, README.md, wiki/CyaSpeechModeExtension.md).
• State Hub bootstrap workstream repo-integration-can-you-assist (id 0a1233fd-75ab-4726-8857-6c97de939069) is active. Its Task T02 ("Write first workplan and initialise workplans/") is the direct driver for creating this file.
• Sibling projects exist and are further along:
  • llm-connect (real Python package with multi-provider adapters, config, tests).
  • phase-memory (foundational workplans complete; local runtime, ports, and contracts exist).
• The repo is still at the pure documentation seed stage (2 commits). No source, tests, or packaging yet.
• grok inspect successfully discovers AGENTS.md and the project context.

Non-Goals (for this MVP slice)

• No implementation of durable, user-controlled memory or complex preference adaptation (define explicit thin ports only; real behavior comes from phase-memory later).
• No voice, speech, or phone-bridge mode (the detailed design in wiki/CyaSpeechModeExtension.md is explicitly future work).
• No autonomous or background execution of generated commands, scripts, or file modifications.
• Do not vendor, copy, or fork code from llm-connect or phase-memory.
• No deep repository indexing, embeddings, vector search, or large-scale content analysis in the first slice.
• No distribution, homebrew/pip packaging polish, or multi-platform installers.
• No long-lived multi-turn conversational REPL or session state machine (one-shot + very lightweight session possible if it falls out naturally).
• No assumption of any specific LLM provider or hosted service.

Success Criteria for This Slice

• cya "..." (and cya --help) can be run from a fresh checkout after a simple editable install and produces useful, context-aware output for the canonical examples in INTENT.md.
• Context collection is transparent and bounded: the user can always see exactly what local information would be sent to the model.
• Any suggestion that the risk classifier marks above "safe" (destructive filesystem operations, force pushes, mass edits, network-affecting commands, etc.) triggers a clear preview + explicit terminal confirmation flow. Nothing executes without the user typing confirmation.
• 100% of LLM interaction (even in tests) flows through a small, well-documented adapter boundary whose shape is compatible with the direction of llm-connect.
• A focused test suite exists with strong coverage of the safety invariants and context-selection rules.
• The workplan file is the source of truth. After the operator runs make fix-consistency, State Hub reflects the tasks and status.
• A new contributor or the sibling teams can read the updated README + this workplan and immediately understand the integration points and non-goals.

Task Breakdown

T01 — Project scaffolding, language choice, and CLI entrypoint

id: CYA-WP-0001-T01
status: todo
priority: high

Bootstrap the minimal runnable package and the primary user-facing command.

• Confirm primary implementation language (strong current signal: Python, driven by .gitignore patterns and the concrete state of the two sibling projects). Record the decision and rationale in this workplan or a short ADR note.
• Create the initial package layout and build configuration (pyproject.toml or equivalent) with:
  • Proper package name (can-you-assist), version, and console script entry point cya.
  • Clean separation: cya/cli/, cya/context/, cya/safety/, cya/llm/ (boundary), cya/memory/ (ports).
• Implement the absolute minimum CLI surface:
  • cya --version
  • cya --help (rich, with examples)
  • cya "free-form natural language request here" (one-shot mode)
  • Basic flags for context control (--file, --no-git, --explain-context, --dry-run).
• Support both one-shot invocation and a very lightweight "session" mode if it falls out naturally from the REPL-less design (future voice bridge will need session tokens).

Acceptance criteria:

• After pip install -e . (or the equivalent for the chosen stack), cya --help and cya --version work with no external services.
• The command accepts a positional request string and prints a structured, human-readable response even before any LLM integration exists (graceful fallback or explicit "no backend configured" message is acceptable in early T01).
• Layout and naming make the future integration seams obvious.

T02 — Safe, transparent, and intentionally bounded local context collector

id: CYA-WP-0001-T02
status: todo
priority: high

Implement the "Context Collector" responsibility described in INTENT.md and SCOPE.md.

Collect only what is necessary for the current request and make the collection completely inspectable.

Minimum sources for MVP (all opt-in or narrowly scoped):

• Current working directory (top-level entries only; respect common ignore patterns such as .git, node_modules, .venv, __pycache__, etc.).
• Git state summary (current branch, dirty status, recent commit subject, list of modified files — obtained via read-only subprocess calls).
• Explicitly provided files or globs via --file / positional arguments.
• Data from stdin when the tool is used in a pipeline.
• Tiny, high-signal environment facts only when clearly relevant (e.g., $SHELL, $EDITOR/$VISUAL).

Hard constraints for this slice:

• No unbounded recursive directory walks.
• No secret scanning or credential harvesting.
• No automatic scraping of shell history, ~/.config, or other user data without an explicit future opt-in + memory layer.
• Collection must produce a stable, serializable ContextEnvelope (or equivalent) that can be pretty-printed for the user and hashed/token-counted for the model.

Acceptance criteria:

• A --show-context / --explain-context (or debug) flag prints exactly the data that would be sent to the LLM, with clear provenance for each piece.
• Tests prove that the collector refuses to traverse known dangerous or expensive locations.
• The collector is a pure module with no side effects beyond read-only inspection.

T03 — Risk classification and mandatory confirmation layer

id: CYA-WP-0001-T03
status: todo
priority: high

This is a core product behavior, not an afterthought.

Build a risk classifier (simple rules + optional LLM assistance for edge cases) that labels suggestions as one of:

• safe
• review (needs a second look)
• destructive / mass-edit / privileged
• network-affecting
• other (with rationale)

For anything above "safe":

• Always emit a clear, copy-pasteable preview of the exact command(s) or action(s) being suggested.
• Show a concise "what will be affected" summary derived from the context envelope.
• Require an explicit confirmation step in the controlling terminal (e.g., Run this? [y/N] or Type 'yes' to proceed).
• Record the confirmation decision in any future audit trail (even if the memory layer is not yet present).

Never auto-execute anything in this slice, even "safe" suggestions, unless the user has explicitly asked for a "run" sub-mode (and even then only after preview).

Acceptance criteria:

• cya "delete every log file older than 30 days in this tree" produces a preview, classifies the action as destructive, and blocks until the user confirms in the terminal.
• The confirmation channel is always the terminal that launched cya (important for the future voice bridge design).
• The classifier and confirmation logic have dedicated tests that are part of the default test run (no live LLM required).

T04 — llm-connect adapter boundary (the integration seam)

id: CYA-WP-0001-T04
status: todo
priority: high

Per SCOPE.md and INTENT.md, can-you-assist owns orchestration and the CLI experience; llm-connect owns provider access.

Define a small, stable interface (protocol / abstract base / typed call) in this repository that all model interaction must go through:

• Something like:

  class LLMAdapter(Protocol):
      def complete(
          self,
          request: AssistanceRequest,   # contains framed intent + packed context + config hints
      ) -> AssistanceResponse:          # contains suggestions, explanation, rationale, risks, raw model output summary
  

• Provide a deterministic fake / mock implementation used by all unit and safety tests.
• Provide a thin concrete adapter (or direct import) that will eventually delegate to the real llm-connect package.
• Configuration surface (which backend, model, temperature, token budget, etc.) must be explicit and delegated to the llm-connect configuration model once the boundary is stable.

Acceptance criteria:

• There is zero production code path that talks to an LLM (or a mock) bypassing this boundary.
• The interface is documented with a short "Integration Guide for llm-connect" section or companion note.
• Switching from the fake to a real (or stubbed) llm-connect client is a small, localized change.

T05 — Thin, explicit phase-memory ports and future hooks

id: CYA-WP-0001-T05
status: todo
priority: medium

Prepare the ground for phase-memory without pulling a dependency or inventing hidden state.

Define clear ports / extension points for the memory capabilities that INTENT.md says must remain under user control:

• Remember a preference or workflow pattern.
• Recall relevant history / preferences for the current cwd + task class.
• Forget / reset (scoped).
• Inspect / export current memory for this project or user.

In the MVP these ports can be:

• Pure no-ops that clearly log "phase-memory not yet connected".
• Or a trivial local JSON file store under an opt-in, user-visible location (~/.config/cya/ or per-project .cya/memory.json), explicitly labeled as a placeholder.

All memory interactions must be behind these ports. No global singletons, no implicit ~/.cache magic, no opaque vendor memory.

Acceptance criteria:

• Code review can point to the exact files/functions that will be replaced or implemented by phase-memory integration.
• The MVP still functions (gracefully) with memory completely disabled.
• README and help text explain the intended memory story and how users will stay in control.

T06 — Assistance orchestrator and prompt/response handling

id: CYA-WP-0001-T06
status: todo
priority: high

The piece that turns raw user intent + collected context into a well-formed request to the LLM adapter and then turns the adapter response into terminal output the user can act on.

Responsibilities:

• Lightweight intent framing (command suggestion vs. explanation vs. summarization vs. plan vs. "help me understand this error").
• Context packing with rough token awareness (so we don't blindly overflow models).
• Prompt construction (or structured request) that includes the safety charter, output schema expectations, and the collected context.
• Post-processing: parse structured output, attach local provenance explanations, produce the final user-facing artifact (suggestion block, rationale, next-step hints).

The orchestrator must be testable in isolation with a fake LLM adapter.

Acceptance criteria:

• The end-to-end flow (context → orchestrator → fake LLM → rendered output) works for at least the four primary use-case families listed in INTENT.md.
• Every response the user sees includes a short "why this answer" section that references the context pieces actually used.

T07 — Test strategy, harness, and safety-focused suite

id: CYA-WP-0001-T07
status: todo
priority: high

Choose and bootstrap a test framework appropriate for a console tool (pytest is the obvious default given the Python signal).

Required test categories for the slice:

• Context collector safety and bounding properties.
• Risk classifier + confirmation flow (the "never auto-execute destructive actions" invariant must be tested).
• Orchestrator behavior with deterministic fake LLM responses (including error and refusal paths).
• CLI surface (help, version, argument parsing, stdin handling).
• Adapter boundary contract tests (the fake satisfies the protocol; swapping implementations is safe).

Prefer fast, hermetic, no-network tests as the default. Any test that touches a real model or external service must be explicitly opt-in (markers, env vars) and skipped in normal CI.

Acceptance criteria:

• pytest (or chosen equivalent) runs cleanly from a fresh checkout with pytest or make test.
• Safety invariants have explicit, readable test names and assertions.
• Coverage or a manual checklist shows the high-risk paths are exercised.

T08 — Documentation, examples, and handoff to siblings / operator

id: CYA-WP-0001-T08
status: todo
priority: medium

Make the MVP usable and the integration points obvious.

• Heavily update README.md with real invocation examples, architecture overview (text diagram is fine), and "How to integrate with llm-connect / phase-memory" guidance.
• Add or expand USAGE.md / docs/ with the canonical workflows.
• In the workplan or a short companion note, explicitly list the extension points and any technical debt discovered during the slice (for later registration in State Hub).
• Ensure the bootstrap workstream tasks that depend on this (SBOM, extension point registration) have clear handoff notes.

Acceptance criteria:

• A person who has never seen the repo before can clone it, follow the updated README, install, and successfully run 2–3 non-trivial cya requests after reading only the README.
• The sibling project owners can read this workplan + the boundary documentation and know exactly where their packages will plug in.

Dependencies & Cross-Repo Coordination

• llm-connect: Supplies the real multi-provider client, config chain, token counting, and structured response helpers. We define the consumption contract here.
• phase-memory: Supplies the actual memory implementation behind the ports we define. We own the call sites and the "user stays in control" contract.
• State Hub (custodian domain): Owns work tracking, progress, decisions, and the fix-consistency sync that will import this workplan's tasks.
• No other hard runtime dependencies for the core MVP loop.

Stack & Technology Choices (Decision Required Before active)

This workplan is intentionally left in ready status until the following are explicitly reviewed and recorded:

• Primary language / runtime (Python is the current leading candidate).
• CLI framework (typer, click, or stdlib argparse + rich for presentation).
• Terminal presentation library (rich, textual, or plain stdlib + colors).
• Configuration format (TOML strongly preferred for alignment with llm-connect patterns).
• Whether an initial pyproject.toml + src layout or a lighter single-file bootstrap is preferred for T01.

Once the stack review is complete, change the workplan status to active and begin implementation (or spawn follow-on workplans if the slice needs to be split).

References & Links

• Parent bootstrap: State Hub workstream repo-integration-can-you-assist (tasks T01–T04)
• This repo: INTENT.md, SCOPE.md, AGENTS.md, README.md, wiki/CyaSpeechModeExtension.md
• Sibling repos (for patterns and interfaces): llm-connect, phase-memory
• State Hub consistency command (run after any workplan or task file change): cd ~/state-hub && make fix-consistency REPO=can-you-assist

---

Status note: Created as the direct output of bootstrap Task T02. This file is the authoritative plan. Do not implement the tasks until the status is moved to active after stack review.