feat: initial cli - #1
Merged
Merged
Conversation
Captures the entity model (Facet → Option → Recipe → Provision), the two-phase resolution pipeline (config.yaml → LogicalConfig → agent files), and the principle that ADE owns agent config format knowledge while MCP servers remain pure runtime. https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
- Scope both docs explicitly to ADE CLI, not the whole ADE concept - Correct package names: @codemcp/workflows-server, @codemcp/knowledge-server, @codemcp/knowledge - Rename commands: init→setup, apply→install - Replace docset with KnowledgeSource (origin-level abstraction) - Catalog is TypeScript code, not YAML — gives type safety and natural versioning - Provision writers import sibling packages directly instead of CLI subprocess - Add custom section in config.yaml for user-managed entries, rest is CLI-only - Resolve all open questions into decisions https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
…provision recipes - Remove agent from config.yaml — it's a generation-time parameter, not a stored choice. Same config works for any supported agent. - Rename "tool" writer to "installable" to avoid ambiguity. - Document that recipes commonly contain multiple provisions targeting different writers (e.g. workflow option → MCP server entry + instructions). https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
Facets can declare dependsOn to reference other facets. The resolver processes facets in topological order and passes a ResolutionContext to provision writers containing the resolved options from dependent facets. This lets writers adapt output based on sibling selections (e.g. testing provisions vary based on which workflow was chosen). https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
Project setup: - Copy template-typescript-monorepo structure (turbo, pnpm, vitest, eslint, prettier, husky pre-commit/pre-push hooks, GitHub CI workflows) - Three packages: @ade/shared (types), @ade/cli, @ade/mcp-server - Shared types implement full entity model from design doc - All packages build and tests pass PRD and design doc updates: - v1 agent writer: OpenCode (not Claude Code/Copilot/Kiro) - Multi-select facets (e.g. frameworks facet) - Dependency prompting: `ade add` prompts for unmet dependent facets - No agent auto-detection, --agent flag required - ADE-managed section delimiters for markdown files - Four v1 facets: process, conventions, documentation, frameworks - Concrete catalog example in TypeScript https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
- Two packages: @ade/core (types, logic, catalog, writers) and @ade/cli (thin shell for arg parsing and TUI). Drop @ade/mcp-server. - Writer contracts use interfaces (ProvisionWriterDef, AgentWriterDef) for runtime extensibility — future packages can register writers without modifying core. - Dispatch via Map-based WriterRegistry, initialized with built-in writers via createDefaultRegistry(). - Built-in writers get internal type safety by defining their own config interfaces and narrowing from Record<string, unknown> at the boundary. - Document the design tension (type safety vs extensibility) and why discriminated unions are insufficient for an open plugin model. https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
Evaluated @clack/prompts, @inquirer/prompts, and Ink against weighted criteria (visual polish, wizard suitability, ESM compatibility, LLM streaming, simplicity, footprint). Clack wins at +14 vs Ink +5 and Inquirer +1 in the Pugh matrix — best fit for a terminating wizard CLI. https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
Rename packages/shared to packages/core (@ade/shared → @ade/core), rename packages/ade to packages/cli, and delete packages/ade-mcp-server. Update all path mappings, aliases, and dependencies accordingly. https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
…erDef - Add ProvisionWriterDef, AgentWriterDef, WriterRegistry interfaces to types - Implement createRegistry, registerProvisionWriter, registerAgentWriter - Implement createDefaultRegistry with stub writers for all 6 provision types + opencode agent - Remove static-structure type tests, replace with behavioral registry tests - 8 behavioral tests covering registration, lookup, overwrite, and default registry https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
The core package's format script runs prettier from its own directory, so it needs its own .prettierignore to skip built output in dist/. https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
mrsimpson
force-pushed
the
claude/add-cli-tui-interface-BofoQ
branch
from
March 14, 2026 19:33
7dc5960 to
55db837
Compare
- Implement instructionWriter (ProvisionWriterDef) that extracts text config and returns it as a LogicalConfig instructions fragment - 5 behavioral tests: text passthrough, multi-line, output shape https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
mrsimpson
force-pushed
the
claude/add-cli-tui-interface-BofoQ
branch
from
March 14, 2026 19:36
d89d6e3 to
f2e1bf4
Compare
- Implement workflowsWriter (ProvisionWriterDef) producing McpServerEntry with npx command and configurable env - 5 behavioral tests https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
mrsimpson
force-pushed
the
claude/add-cli-tui-interface-BofoQ
branch
from
March 14, 2026 19:40
db86ef5 to
d8b07cf
Compare
- Implement getDefaultCatalog(), getFacet(), getOption() lookup functions - Add process facet with codemcp-workflows and native-agents-md options - 6 behavioral tests including registry integration check https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
mrsimpson
force-pushed
the
claude/add-cli-tui-interface-BofoQ
branch
from
March 14, 2026 19:43
f0fdcc5 to
2584b51
Compare
- Implement readUserConfig/writeUserConfig for config.yaml - Implement readLockFile/writeLockFile for config.lock.yaml - Add yaml package dependency - 7 behavioral tests: roundtrip, null on missing, multi-select, custom section https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
mrsimpson
force-pushed
the
claude/add-cli-tui-interface-BofoQ
branch
from
March 14, 2026 19:47
8359681 to
5039605
Compare
- Implement resolve(userConfig, catalog, registry) producing merged LogicalConfig - Supports single-select facets, custom section merge, mcp_server dedup by ref - Throws on unknown options, silently skips unknown facets - 8 behavioral tests including integration with real writers and catalog https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
mrsimpson
force-pushed
the
claude/add-cli-tui-interface-BofoQ
branch
from
March 14, 2026 19:51
9a5cbf9 to
1a71f47
Compare
- Implement runSetup() orchestrating facet selection, resolution, and config writing - Uses @clack/prompts for intro/outro, select prompts with skip option - Supports user cancellation, skippable facets - 5 behavioral tests with mocked @clack/prompts and @ade/core - Add @clack/prompts dependency https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
mrsimpson
force-pushed
the
claude/add-cli-tui-interface-BofoQ
branch
from
March 14, 2026 20:01
9065cb5 to
128d034
Compare
Root-level eslint config (unlike package-level) enforces no-unused-vars on test files. Remove UserConfig and LockFile type imports that were only used inside vi.mock() factory context. https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
mrsimpson
changed the title
mrsimpson
changed the title
Exercises the full pipeline end-to-end (catalog → resolver → YAML I/O) with only @clack/prompts mocked. Verifies config.yaml and config.lock.yaml are written correctly for both process options, cancellation produces no files, and YAML roundtrips cleanly. Also exports getDefaultCatalog, getFacet, getOption from @ade/core. https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
Wire up `ade setup [dir]` as a runnable command. Uses the real catalog and calls runSetup with @clack/prompts TUI. Also supports `--version` and prints usage on unknown commands. https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
Version 2.3.0 of @codemcp/skills now ships type declarations for its ./api export, so the hand-written codemcp-skills.d.ts is no longer needed. https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
The single "conventions" facet conflated two fundamentally different kinds of choices. Architecture (e.g. TanStack) is a constraining, single-select stack decision. Practices (TDD, ADR, Conventional Commits) are composable, multi-select disciplines orthogonal to any stack. - Add architecture facet (single-select): stack/framework conventions - Add practices facet (multi-select): composable development disciplines - Remove conventions facet (replaced by the two above) - Update CLI setup flow, tests, and README documentation https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
…tices subtypes The three-layer model (Process → Conventions → Documentation) stays intact. Architecture and Practices are now presented as two sub-categories within the Conventions layer, not as replacements for it. https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
Docsets are derived from upstream selections (architecture, practices) rather than being a standalone facet. Each Option can declare recommended docsets which the resolver collects, deduplicates, and maps to knowledge_sources. The TUI presents them as a confirmation step (opt-out). - Add DocsetDef type on Option, excluded_docsets on UserConfig - Resolver collects docsets into knowledge_sources with dedup and exclusion - Add collectDocsets() helper for TUI pre-resolution - Enrich tanstack option with Router/Query/Form/Table docsets - Enrich conventional-commits with spec docset - Setup TUI presents docset multiselect after facet selection - Update design doc with docsets model and design decision #7 https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
- Implement knowledgeWriter provision writer (produces knowledge_sources) - Replace knowledge stub in registry with real writer - Resolver auto-adds @codemcp/knowledge-server MCP entry when knowledge_sources are present - Add knowledge-installer in CLI: calls createDocset + initDocset from @codemcp/knowledge programmatic API - Wire installKnowledge into setup and install commands - Add type declarations for @codemcp/knowledge API - Add @codemcp/knowledge@2.1.0 dependency to @ade/cli https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
Remove hand-written knowledge-api.d.ts — the package ships exports.d.ts with full typed API at packages/cli/dist/exports.d.ts. Revert the .gitignore !*-api.d.ts exception since it's no longer needed. https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
…ests - Fix all docset origins to use valid .git repository URLs required by createDocset's git-repo preset validation - Add knowledge integration tests verifying createDocset + initDocset calls, docset exclusion, and MCP server entry in settings.json - Fix existing tanstack integration tests to mock the docset confirmation multiselect - Remove unused DocsetDef import (lint fix) https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
- Replace 4-facet model (process/conventions/documentation/frameworks) with actual 3-facet model (process/architecture/practices) - Document docsets as weak entity on Option with opt-out confirmation - Update agent writer: OpenCode → Claude Code with actual output files - Update package structure to reflect existing files - Update registry example to match createDefaultRegistry() - Update knowledge writer example with .git URLs and createDocset API - Update skills writer example with inline/external skill definitions - Add knowledge-installer and skills-installer to CLI structure - Remove references to unimplemented commands (add/remove/status) from package structure (kept in CLI Commands as planned) https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
install command: - Reads config.lock.yaml directly instead of re-resolving from config.yaml - No longer writes the lock file — treats it as immutable input - Fails with clear message when lock file is missing setup command: - Reads existing config.yaml and pre-selects previous choices as defaults (initialValue for select, initialValues for multiselect) - Warns when a previous selection references an option no longer in catalog - Stale options are silently dropped from initialValue (not pre-selected) Removed from docs and CLI help: - ade add / ade remove / ade status commands (re-run setup instead) - dependsOn facet dependencies (not implemented, not needed) - installable writer and CliAction type (vestigial) - Updated LogicalConfig to show skills[] instead of cli_actions[] https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
Create a new published package @ade/harnesses with writers for 6 coding agent harnesses: Claude Code, Cursor, GitHub Copilot, Windsurf, Cline, and Roo Code. Each writer generates the appropriate MCP config and instruction files for its platform. Key changes: - New @ade/harnesses package with HarnessWriter interface extending AgentWriterDef with label/description metadata - Claude Code: .claude/settings.json + AGENTS.md (moved from core) - Cursor: .cursor/mcp.json + .cursor/rules/ade.mdc - GitHub Copilot: .vscode/mcp.json + .github/copilot-instructions.md + dedicated .github/agents/ade.agent.md agent definition - Windsurf: .windsurf/mcp.json + .windsurfrules - Cline: .cline/mcp.json + .clinerules - Roo Code: .roo/mcp.json + .roorules - Setup wizard now includes harness multi-select as final step - Install command supports --harness flag (comma-separated) - UserConfig and LockFile store selected harnesses - Legacy --agent flag preserved as alias https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
Add eslint and vitest tsconfig, remove unused import. https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
Add harness writers for Kiro (.kiro/agents/ade.json) and OpenCode (opencode.json + .opencode/agents/ade.md). Add allowedTools field to McpServerEntry type and wire alwaysAllow tool permissions into Cline, Roo Code, and Windsurf writers (defaulting to wildcard). Remove legacy --agent CLI flag. https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
- Add "universal" harness writer (AGENTS.md + .mcp.json) as cross-tool standard, set as default instead of claude-code - Update Claude Code writer to generate .claude/agents/ade.md custom agent definition, .mcp.json for MCP servers, and .claude/settings.json with MCP tool permission allow-rules - Update Copilot writer to include built-in tools + MCP wildcards in .github/agents/ade.agent.md tools list - Fix OpenCode writer to use "mcp" top-level key (not "mcp_servers") with type:"local" per upstream reference implementation - Update all integration tests for new file locations https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
The .github/agents/*.agent.md format is read by both VS Code Copilot and GitHub Copilot CLI. Update the description to reflect this. https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
- Remove copilot-instructions.md generation; .github/agents/ade.agent.md is the preferred custom agent format for both VS Code and CLI - Fix knowledge-server MCP ref from "@codemcp/knowledge-server" to "knowledge" (short ref, consistent with other servers) - Remove instruction provisions from architecture and practices facets; these facets now produce only skills and MCP servers, not system prompt instructions. Only the process facet generates instructions. - Replace automatic knowledge init during setup/install with a post-setup hint directing users to run `npx @codemcp/knowledge init` separately https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
… 9 harness writers The resolver now auto-adds the agentskills (skills-server) MCP entry when skills are present, matching the existing pattern for knowledge-server. This removes identical conditional logic from all 9 harness writers (-131 lines, +61 lines net). https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
…ource The supported agents list evolves frequently. Point to the source of truth instead of maintaining a static list in prose. https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
…cated core agent - Extract shared utilities (readJsonOrEmpty, writeJson, writeMcpServers, writeRulesFile, writeAgentMd, writeInlineSkills) into harnesses/src/util.ts - Rewrite all 9 harness writers to use shared utilities (~700 lines removed) - Move skills-installer from CLI to harnesses package (domain responsibility) - Remove deprecated core/src/agents/claude-code.ts (replaced by harnesses) - Remove stale @codemcp/skills/api mocks from CLI tests https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
mrsimpson
force-pushed
the
claude/add-cli-tui-interface-BofoQ
branch
from
March 17, 2026 20:06
7b79b7e to
5b866a0
Compare
Incorporate concepts from HumanLayer's "Skill Issue" article to connect ADE's information architecture to the broader harness engineering practice. - Reference harness engineering in "Why this is needed" and cite ETH Zurich agentfile study - Add "Where ADE fits" section mapping ADE's three layers to information levers and acknowledging complementary runtime levers (sub-agents, hooks, back-pressure) - Add "bias towards shipping" guidance in Customization - Add Further Reading section linking the article https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
mrsimpson
changed the title
Teaches Claude how to add new options, practices, facets, and provision writers to the ADE catalog — following the exact code paths and conventions used in the project. https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
Remove code samples and type summaries that can be read from source. Keep only conceptual guidance and file locations. https://claude.ai/code/session_01GCqwdfAMznLZZ97tYfJXRa
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Provides an initial version of a cli for harness scaffolding.