vgxness 0.1.0

package/docs/harness-gap-analysis.md

@@ -0,0 +1,229 @@
+# Harness Systems Gap Analysis
+
+This research compares current agent harness patterns against the `vgxness` PRD and identifies what the product still needs before it can become a serious local-first SDD harness.
+
+## Executive summary
+
+The current PRD has the right product direction: local-first, provider-agnostic, memory-backed, SDD-first, and agent/subagent aware.
+
+What is still missing is the **runtime contract**: permissions, sandboxing, run state, provider adapters, observability, evaluation, and artifact portability. Without these, `vgxness` risks becoming “memory + prompts” instead of a real harness.
+
+## Systems reviewed
+
+| System | Relevant lessons for `vgxness` |
+|---|---|
+| Anthropic agent patterns | Keep workflows simple and composable; distinguish predictable workflows from autonomous agents; invest heavily in tool design and transparency. |
+| Claude Code subagents | Subagents need isolated context, explicit tools, permissions, model selection, memory scopes, lifecycle hooks, and clear delegation descriptions. |
+| OpenCode agents | Provider/tool configuration should support primary agents, subagents, per-agent permissions, model routing, task permissions, and markdown/JSON definitions. |
+| OpenAI Agents SDK | Useful primitives: agents, handoffs, agents-as-tools, guardrails, sessions, human-in-the-loop, tracing, MCP, sandbox agents, and resumable workspaces. |
+| LangGraph | Durable execution, checkpoints, streaming, human-in-the-loop, stateful workflows, memory, and deep traces matter for long-running agents. |
+| AutoGen | Multi-agent systems benefit from layers: simple AgentChat, lower-level event-driven Core, extensions, distributed runtimes, and UI/studio tooling. |
+| CrewAI | Productized multi-agent systems commonly include agents, crews, flows, tasks, memory, knowledge, guardrails, observability, persistence, and resume. |
+
+## What the PRD already covers well
+
+- Local-first memory.
+- Project and personal/global memory scopes.
+- SDD-first workflow.
+- Agent and subagent registry from the MVP.
+- Provider-agnostic model with OpenCode/Claude Code adapters.
+- CLI for setup/configuration and integrations for day-to-day usage.
+- Cloud sync and team workflows correctly deferred until later.
+
+## Missing or underdefined areas
+
+### 1. Runtime/run model
+
+`vgxness` needs a first-class concept of a **run**.
+
+Minimum fields:
+
+- run id
+- project id/path
+- user intent
+- phase/workflow
+- selected agent/subagent
+- provider adapter
+- model
+- tool calls
+- artifacts read/written
+- memory reads/writes
+- approvals
+- verification evidence
+- final status
+
+Why it matters: without runs, the harness cannot resume, debug, audit, or explain agent behavior.
+
+### 2. Permission and sandbox model
+
+The PRD mentions agents and integrations, but not the security boundary.
+
+Needed capabilities:
+
+- Read/write/shell/network/git/memory permission categories.
+- Per-agent and per-tool permissions.
+- Human approval gates for destructive, external, or privileged operations.
+- Workspace boundary enforcement.
+- Optional sandbox/worktree strategy for implementation agents.
+
+This is NOT optional. A harness that can run agents without strong permissions is a loaded weapon.
+
+### 3. Provider adapter contract
+
+Provider-agnostic intent is correct, but the PRD needs an adapter interface.
+
+Each adapter should declare:
+
+- supported agent definition fields
+- supported permissions
+- supported memory injection modes
+- supported subagent/task model
+- supported hooks/lifecycle events
+- config file locations
+- limitations
+- export/render format
+
+This prevents `vgxness` from pretending all tools support the same features.
+
+### 4. Agent definition schema
+
+The agent registry needs a neutral schema, not just “store agents”.
+
+Suggested minimum schema:
+
+- name
+- description/delegation trigger
+- role/system instructions
+- mode: primary/subagent/workflow-phase
+- capabilities
+- allowed tools
+- denied tools
+- model preference
+- memory scopes
+- SDD phases supported
+- max steps/turns
+- required approvals
+- adapter overrides
+
+### 5. Tool/ACI design
+
+Agent-computer interface design is a product feature.
+
+Needed:
+
+- Tool descriptions optimized for model usage.
+- Safe input schemas.
+- Examples and edge cases per tool.
+- Clear boundaries between similar tools.
+- Tool-level tests/evals to catch misuse.
+
+Bad tools create bad agents. This is where a lot of harnesses quietly fail.
+
+### 6. Durable execution and resume
+
+SDD creates long-running work. Long-running work needs checkpoints.
+
+Needed:
+
+- run checkpoints
+- phase checkpoints
+- apply-progress merge rules
+- resumable interrupted runs
+- idempotency expectations for tools
+- failure classification: blocked, failed, needs-human, cancelled, completed
+
+### 7. Observability and debugging
+
+The product needs traces, not just logs.
+
+Minimum trace entities:
+
+- run
+- phase
+- agent/subagent invocation
+- tool call
+- memory operation
+- artifact operation
+- approval decision
+- verification command/result
+
+Nice-to-have later:
+
+- token/cost tracking
+- model latency
+- failure heatmap
+- timeline UI/export
+
+### 8. Evaluation and quality gates
+
+The PRD has success criteria, but not evals.
+
+Needed MVP evals:
+
+- agent resolution chooses the expected agent
+- SDD artifact chain remains complete
+- memory upsert/revision behavior is durable
+- provider adapter renders valid config
+- permission model blocks unsafe operations
+- resume restores the expected run state
+
+### 9. Artifact portability
+
+Memory-only artifacts are fast, but PRD/review workflows need portability.
+
+Needed:
+
+- export SDD artifacts to markdown/json
+- import artifacts back into memory
+- snapshot a run for debugging or sharing
+- redact sensitive data during export
+
+### 10. CLI surface definition
+
+The PRD says CLI, but the first command set is still open.
+
+Candidate MVP commands:
+
+- `vgx init`
+- `vgx memory search|get|save|update`
+- `vgx agent list|add|render|validate`
+- `vgx sdd new|continue|status|archive`
+- `vgx run list|show|resume`
+- `vgx adapter doctor|render`
+
+## Recommended MVP additions to PRD
+
+Add these as explicit MVP requirements:
+
+1. **Run lifecycle model** — every agentic operation is captured as a resumable/auditable run.
+2. **Permission model** — per-agent tool permissions with human approval gates.
+3. **Provider adapter contract** — adapters translate neutral `vgxness` definitions into provider-specific configs.
+4. **Agent schema** — neutral registry schema for agents/subagents/workflow-phase agents.
+5. **Trace model** — structured trace records for runs, tools, memory, artifacts, approvals, and verification.
+6. **Artifact export/import** — SDD and memory artifacts can be exported for review/debugging.
+7. **Evaluation harness** — tests/evals for agent resolution, adapters, permissions, memory, and resume.
+
+## Suggested next SDD change
+
+Create a new SDD change named `harness-runtime-foundation`.
+
+Scope it narrowly:
+
+- define run lifecycle schema
+- define agent registry schema
+- define permission categories
+- define provider adapter interface
+- add CLI validation/render skeleton
+- add tests for schemas and adapter rendering
+
+Do **not** implement full cloud sync, distributed agents, web UI, or team workflows yet.
+
+## Sources
+
+- Anthropic: Building effective agents
+- Claude Code: subagents documentation
+- OpenCode: agents documentation
+- OpenAI Agents SDK documentation
+- LangGraph overview
+- Microsoft AutoGen documentation
+- CrewAI documentation

package/docs/prd.md

@@ -0,0 +1,372 @@
+# vgxness PRD
+
+`vgxness` is a local-first, Gentle-AI-like agentic harness for advanced individual developers who want to configure AI coding tools, coordinate agents/subagents, use persistent memory, and run SDD workflows with explicit runtime state.
+
+## Product thesis
+
+AI coding tools are powerful, but their work is often fragmented: context is lost between sessions, agents are configured differently per tool, and substantial changes lack a repeatable planning/verification workflow.
+
+`vgxness` solves this by providing a provider-agnostic harness layer with persistent memory, agent/subagent configuration, model/profile management, MCP tools, an intuitive CLI/TUI, and SDD-first development flows.
+
+The product intentionally overlaps with systems such as Gentle-AI and `gentle-pi`: it should configure AI agents, install/sync SDD assets, wire memory, and support per-phase agent/model behavior. Its differentiator is that the workflow must not live only in prompts or agent instructions. `vgxness` should also maintain a **verifiable runtime control plane**: explicit phase state, readiness gates, artifacts, runs, approvals, checkpoints, and audit trails.
+
+## Reference positioning
+
+| Reference system | What it proves | What `vgxness` should learn | Where `vgxness` differentiates |
+|---|---|---|---|
+| Gentle-AI | AI coding tools can be upgraded through installed prompts, skills, SDD agents, model profiles, permissions, backups, and verification. | Installer/sync discipline, provider adapters, per-phase model routing, safe file merging, backups, golden tests. | Add a first-class local runtime state engine instead of relying only on configured agent behavior. |
+| `gentle-pi` | Pi can own persona, SDD agents/chains, strict TDD support, safety rules, model assignment, and Engram wiring as packages. | Package-owned runtime behavior, startup asset checks, project-local SDD assets, child-agent communication. | Expose provider-neutral APIs for phase readiness, artifact state, run history, approvals, and resumable checkpoints across tools. |
+| Engram | Persistent memory can preserve decisions, discoveries, prompts, SDD artifacts, and sessions across agent runs. | Memory as infrastructure, project detection, topic-key upserts, revisions, session summaries. | Treat memory as one backend behind explicit workflow/run state, not the only source of truth. |
+
+## Primary user
+
+| Segment | Priority | Description |
+|---|---:|---|
+| Advanced individual developer | MVP | A power user working with AI coding tools who needs durable context, structured workflows, and reusable agent configuration. |
+| Development teams | Future | Teams that need shared workflows, governance, permissions, audit trails, PR coordination, and cloud sync. |
+
+## MVP scope
+
+The MVP must prove that a single developer can use `vgxness` locally to manage agentic development work with less context loss and more reliable execution. It must feel comparable to a modern agent ecosystem harness while proving one stronger claim: SDD state can be queried, gated, resumed, and audited through product APIs instead of depending only on LLM discipline.
+
+### 1. Local-first memory
+
+The product must support persistent memory without requiring a cloud account.
+
+Minimum capabilities:
+
+- Project memory for repository-specific decisions, SDD artifacts, sessions, progress, and codebase discoveries.
+- Personal/global memory for user preferences, reusable patterns, standards, and cross-project learnings.
+- Search, read, create, update, and topic-key upsert flows.
+- Durable revisions for evolving observations and artifacts.
+- Traceability for why memory was created or updated.
+
+### 2. SDD-first workflow
+
+The product must make Spec-Driven Development the primary development path.
+
+Minimum canonical workflow:
+
+1. Explore
+2. Proposal
+3. Spec
+4. Design
+5. Tasks
+6. Apply progress
+7. Verify
+8. Archive
+
+Canonical artifact phase keys use `proposal` and `apply-progress`. User-facing commands may later expose friendlier verbs such as “propose” or “apply,” but stored workflow state must use one canonical vocabulary.
+
+Minimum capabilities:
+
+- Persist SDD artifacts in memory.
+- Expose phase status, readiness, and missing prerequisites through CLI/API/MCP calls.
+- Block or warn before a phase runs without required artifacts or approvals.
+- Continue interrupted changes from stored state.
+- Track apply progress without overwriting previous work.
+- Support review workload planning for large changes.
+- Keep verification results linked to specs, tasks, runs, and evidence.
+
+### 3. Agent and subagent registry
+
+The product must include agent/subagent registration and configuration from the start.
+
+Minimum capabilities:
+
+- Define agents and subagents in a provider-neutral model.
+- Describe capabilities, instructions, permissions, memory access, and compatible workflows.
+- Resolve which agents should be used for a task.
+- Render or preview provider-specific agent/subagent configuration from neutral definitions.
+- Support future provider adapters without changing the core domain model.
+
+### 4. Skill registry and controlled self-improvement
+
+The product must manage skills as first-class reusable assets, not just static prompt files.
+
+Minimum capabilities:
+
+- Register skills independently from agents and workflows.
+- Attach skills to agents, subagents, SDD phases, or provider adapters.
+- Track skill versions, sources, compatibility, and usage history.
+- Evaluate whether a skill helped or failed during a run.
+- Propose skill improvements from traces, failures, repeated corrections, and memory discoveries.
+- Generate reviewable skill diffs instead of silently mutating active skills.
+- Require human approval before a proposed skill improvement becomes active.
+
+Self-improvement loop:
+
+1. Observe runs, traces, failures, and repeated user corrections.
+2. Detect a candidate improvement.
+3. Draft a skill update as a versioned proposal.
+4. Evaluate the proposal against relevant scenarios.
+5. Ask for human approval.
+6. Activate the approved version and preserve rollback history.
+
+### 5. MCP server, CLI, TUI, and integrations
+
+The product must provide three first-class interfaces over the same local core:
+
+- **MCP server** for agent-facing workflow/state tools.
+- **CLI** for scriptable setup, inspection, and automation.
+- **TUI** for guided installation, onboarding, configuration, and visual status.
+
+The core rule: MCP, CLI, and TUI must call the same services and storage. They must not each reimplement workflow rules.
+
+#### MCP server
+
+The MCP server is the main integration surface for AI coding tools. It should expose safe, typed tools that let agents query and update product state without editing config files directly.
+
+Minimum MCP capabilities:
+
+- Start a local MCP server through `vgx mcp start` or an installed provider config.
+- Install MCP integration for supported tools through guided setup.
+- Expose SDD status, readiness, next-phase, and artifact operations.
+- Expose run start/checkpoint/finalize and approval-request operations.
+- Expose agent resolution and skill payload operations.
+- Return actionable blocked states instead of relying on prompt interpretation.
+
+Candidate MCP tools:
+
+```text
+vgxness_sdd_status
+vgxness_sdd_next
+vgxness_sdd_ready
+vgxness_sdd_save_artifact
+vgxness_run_start
+vgxness_run_checkpoint
+vgxness_run_request_approval
+vgxness_agent_resolve
+vgxness_skill_payload
+vgxness_profile_get
+```
+
+#### CLI
+
+The CLI must be intuitive, predictable, and useful without reading internal docs.
+
+Minimum CLI capabilities:
+
+- Initialize `vgxness` in a project.
+- Install/sync managed agent assets without clobbering user-owned config.
+- Install, inspect, and remove MCP integration for supported tools.
+- Configure memory scopes and storage.
+- Configure agents and subagents.
+- Configure per-phase model/profile assignments.
+- Inspect SDD artifacts and memory.
+- Export or debug product state.
+- Verify installation/configuration health and report rollback options.
+
+Candidate CLI shape:
+
+```bash
+vgx init
+vgx doctor
+vgx status
+vgx mcp install opencode
+vgx mcp status
+vgx sdd status <change>
+vgx sdd next <change>
+vgx profiles list
+vgx profiles set apply <model>
+```
+
+#### TUI
+
+The TUI is the default human onboarding and local operations surface. It should optimize for the next meaningful decision, not decorative metrics.
+
+Minimum TUI screens:
+
+- **Setup** — detect environment/project state, choose providers, inspect agents, run verification, and show copy-only external setup guidance without silent provider writes.
+- **Workflows** — available workflow paths and safe next actions.
+- **Runs** — run history, current run state, blockers, and resumable execution.
+- **Approvals** — pending permission requests and safety gates.
+- **Agents** — registered agents/subagents, attached skills, model/profile routing, and provider compatibility.
+- **SDD** — change list, phase progress, missing artifacts, next ready phase, blockers, and resumable runs.
+- **Doctor** — health checks, broken config, MCP availability, memory status, adapter issues, and suggested fixes.
+- **Settings** — local preferences and configuration status without silent provider writes.
+
+TUI state requirements:
+
+- Loading, empty, error, success, blocked, and permission states must be explicit and actionable.
+- Keyboard navigation and visible focus are required.
+- The dashboard TUI is read-only; provider config writes/install/apply are external-only, require explicit confirmation outside the dashboard, and are not run by dashboard flows.
+
+#### Installation experience
+
+Installation should be step-based and avoid manual JSON editing for the happy path.
+
+Target flow:
+
+```text
+1. Install binary
+2. Run `vgx`
+3. Select AI tools
+4. Install MCP integration
+5. Configure memory
+6. Choose SDD mode/profile
+7. Run doctor
+8. Open the AI tool and start working
+```
+
+The same flow must be available through CLI flags for automation and CI-friendly dry runs.
+
+Initial integration targets:
+
+- OpenCode
+- Claude Code
+
+Pi/`gentle-pi` is a design reference and future adapter target, not part of the first integration target list unless the MVP scope is explicitly expanded.
+
+The integration model must remain provider-agnostic. Tool-specific behavior belongs in adapters, not in the core domain.
+
+### 6. Harness runtime foundation
+
+The product must model agentic work as explicit, auditable, resumable runs.
+
+Minimum capabilities:
+
+- Create a run record for each meaningful agentic operation.
+- Track user intent, project, workflow phase, selected agent, provider adapter, model, artifacts, memory operations, approvals, tool calls, verification evidence, and final status.
+- Support interrupted work through checkpoints and resumable run state.
+- Classify run outcomes: completed, failed, blocked, cancelled, needs-human, or partially-complete.
+- Keep run state separate from long-term memory and SDD artifacts.
+
+### 7. Permission and sandbox model
+
+The product must treat agent permissions as a core safety feature, not as adapter-specific behavior.
+
+Minimum capabilities:
+
+- Define permission categories for read, write/edit, shell, network, git, memory, external directories, and provider-specific tools.
+- Support per-agent and per-subagent permissions.
+- Require human approval for destructive, external, privileged, or ambiguous operations.
+- Enforce workspace boundaries.
+- Support future isolated execution strategies, such as worktrees or sandboxes, for implementation agents.
+
+### 8. Provider adapter contract
+
+The product must translate `vgxness` concepts into provider-specific configuration through adapters.
+
+Each adapter must declare:
+
+- Supported agent definition fields.
+- Supported skill definition and injection modes.
+- Supported permission categories.
+- Supported memory injection modes.
+- Supported subagent/task delegation model.
+- Supported hooks or lifecycle events.
+- Config file locations.
+- Known limitations.
+- Render/export format.
+
+Adapters must not redefine the core product model.
+
+### 9. Observability and evaluation
+
+The product must make agentic behavior inspectable and testable.
+
+Minimum observability capabilities:
+
+- Structured traces for runs, phases, agent invocations, tool calls, memory operations, artifact operations, approvals, and verification commands.
+- Debuggable timelines for completed or failed runs.
+- Redaction strategy for sensitive data before export or sharing.
+
+Minimum evaluation capabilities:
+
+- Agent resolution chooses the expected agent for representative tasks.
+- Skill resolution injects the expected reusable guidance for representative tasks.
+- Skill improvement proposals are reviewable, versioned, and gated by approval.
+- SDD artifact chains remain complete and linked.
+- Memory revision/upsert behavior remains durable.
+- Provider adapters render valid config.
+- Permission rules block unsafe operations.
+- Resume restores expected run state.
+
+### 10. Artifact portability
+
+The product must support memory-first operation without trapping artifacts inside memory only.
+
+Minimum capabilities:
+
+- Export SDD artifacts to Markdown or JSON.
+- Import exported artifacts back into memory.
+- Snapshot runs for debugging or review.
+- Redact sensitive data during export.
+
+## Non-goals for MVP
+
+- Cloud sync.
+- Multi-user collaboration.
+- Team permissions and governance.
+- Web dashboard.
+- Hosted memory service.
+- Marketplace for agents.
+- Full provider parity across every AI coding tool.
+- Distributed multi-worker execution.
+- Production cloud-hosted tracing.
+- Fully autonomous, unreviewed skill mutation.
+
+These are future expansion areas, not MVP blockers.
+
+## Product principles
+
+| Principle | Meaning |
+|---|---|
+| Local-first | The developer owns their data and can work offline. |
+| Provider-agnostic | Core concepts must not be coupled to OpenCode, Claude Code, or any single vendor. |
+| SDD-first | Substantial work should move through explicit planning, implementation, verification, and archive phases. |
+| MCP-first for agents | AI tools should interact with the harness through typed MCP tools instead of prompt-only conventions. |
+| Guided by default | The TUI should make setup and diagnosis understandable without manual config editing. |
+| Memory as infrastructure | Memory is not a chat convenience; it is a durable product substrate. |
+| Reviewable work | The system should help keep work units understandable, traceable, and verifiable. |
+| Safe by default | Agents must operate inside explicit permissions and auditable boundaries. |
+| Inspectable runtime | Every meaningful agentic operation should be explainable after it happens. |
+| Controlled self-improvement | The system may propose better skills, but humans approve what becomes active. |
+
+## Future roadmap
+
+After the MVP proves local individual usage, expand toward:
+
+- Cloud sync across machines.
+- Team/shared memory spaces.
+- Permissions, governance, and audit trails.
+- PR and chained-PR coordination.
+- Hosted dashboard for inspection and collaboration.
+- Additional provider adapters.
+- Import/export between local and cloud memory backends.
+- Distributed agent workers.
+- Hosted observability and evaluation dashboard.
+- Skill marketplace or shared skill catalog.
+
+## Success criteria
+
+The MVP is successful when an advanced individual developer can:
+
+- Initialize `vgxness` in a repo.
+- Complete the guided TUI setup without manually editing provider config.
+- Install and verify MCP integration for at least one AI coding tool.
+- Configure personal and project memory.
+- Register agents/subagents in a provider-neutral way.
+- Register skills, attach them to agents/workflows, and review proposed improvements.
+- Run an SDD change from idea through archive.
+- Resume work across sessions without losing critical context.
+- Use at least one external AI coding tool integration through an adapter.
+- Use the CLI to inspect status, run doctor, and debug product state.
+- Inspect a run timeline with agents, tools, memory/artifact operations, approvals, and verification evidence.
+- Validate that unsafe operations are blocked or require approval.
+
+## Open questions
+
+- What is the first integration adapter: OpenCode or Claude Code?
+- Should memory storage be per-repo by default, with global memory in a user-level directory?
+- What config format should define agents/subagents?
+- What config format should define skills and skill versions?
+- Which skill improvement proposals should require approval versus automatic rejection?
+- Which commands form the first public CLI surface?
+- Which TUI framework should be used for the first implementation?
+- Should the MCP server run only over stdio for MVP, or also support local HTTP later?
+- What is the safest default install command and update channel?
+- What privacy/export guarantees are required before public release?
+- What is the first sandbox strategy: normal workspace, git worktree, or process/container isolation?
+- What trace format should be used for local inspection and future cloud sync?

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "vgxness",
+  "version": "0.1.0",
+  "description": "Alpha CLI and MCP control plane for guided AI-agent workflows, SDD, memory, and OpenCode setup.",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uzielvgx/vgxness.git"
+  },
+  "homepage": "https://github.com/uzielvgx/vgxness#readme",
+  "bugs": {
+    "url": "https://github.com/uzielvgx/vgxness/issues"
+  },
+  "keywords": [
+    "mcp",
+    "opencode",
+    "agents",
+    "sdd",
+    "cli"
+  ],
+  "type": "module",
+  "scripts": {
+    "cli": "tsx src/cli/index.ts",
+    "build": "tsc -p tsconfig.build.json && node scripts/copy-migrations.mjs",
+    "prepack": "npm run build",
+    "package:dry-run": "npm pack --dry-run --json",
+    "package:release-check": "node scripts/validate-package-release.mjs",
+    "package:smoke:install": "node scripts/smoke-tarball-install.mjs",
+    "test": "node --import tsx --test \"test/**/*.test.ts\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "bin": {
+    "vgxness": "dist/cli/index.js",
+    "vgx": "dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "package.json",
+    "README.md",
+    "LICENSE",
+    "docs"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "better-sqlite3": "^11.10.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.15.18",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}