From 02cbb0fe893311bdfe8865cdf66eff2d83bb3785 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oliver=20J=C3=A4gle?= Date: Thu, 19 Mar 2026 11:33:44 +0100 Subject: [PATCH 1/3] WIP: transition to implement --- .beads/issues.jsonl | 4 ++ .beads/last-touched | 2 +- ...-ade-better-in-cli-explanation-b8jcv3.json | 24 ++++++++ ...elopment-plan-better-in-cli-explanation.md | 60 +++++++++++++++++++ 4 files changed, 89 insertions(+), 1 deletion(-) create mode 100644 .vibe/beads-state-ade-better-in-cli-explanation-b8jcv3.json create mode 100644 .vibe/development-plan-better-in-cli-explanation.md diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 7c3caf4..33d7cc7 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -56,3 +56,7 @@ {"id":"ade-4.3","title":"Fix","description":"Implement the solution based on your analysis: - If exists: Follow the design from it - Otherwise: Elaborate design options and present them to the user Before implementing, assess the approach: - How critical is this system? What is the blast radius if the fix causes issues? - Should this be a minimal fix or a more comprehensive solution? Make targeted changes that address the root cause without introducing new issues. Be careful to maintain existing functionality while fixing the bug.","status":"open","priority":3,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-03-19T10:33:07.076548+01:00","created_by":"Oliver Jägle","updated_at":"2026-03-19T10:33:07.076548+01:00","dependencies":[{"issue_id":"ade-4.3","depends_on_id":"ade-4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"ade-4.3","depends_on_id":"ade-4.2","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]} {"id":"ade-4.4","title":"Verify","description":"Test the fix thoroughly to ensure the original bug is resolved and no new issues were introduced. Run existing tests, create new ones if needed, and verify the solution is robust.","status":"open","priority":3,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-03-19T10:33:07.222264+01:00","created_by":"Oliver Jägle","updated_at":"2026-03-19T10:33:07.222264+01:00","dependencies":[{"issue_id":"ade-4.4","depends_on_id":"ade-4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"ade-4.4","depends_on_id":"ade-4.3","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]} {"id":"ade-4.5","title":"Finalize","description":"Ensure code quality and documentation accuracy through systematic cleanup and review. **STEP 1: Code Cleanup** Systematically clean up development artifacts: - Remove all temporary debug output statements used during bug investigation (console logging, print statements, debug output functions) - Address each TODO/FIXME comment by either implementing the solution or documenting why it's deferred - Remove completed TODOs and convert remaining ones to proper issue tracking if needed - Remove temporary debugging code, test code blocks, and commented-out code - Ensure proper error handling replaces temporary debug logging **STEP 2: Documentation Review** Review and update documentation to reflect the bug fix: - If exists, update it if design details were refined or changed during the fix - Compare documentation against the actual bug fix implementation - Update only the documentation sections that have functional changes - Remove references to investigation iterations, progress notes, and temporary decisions - Ensure documentation describes the final fixed state, not the debugging process - Ask the user to review document updates **STEP 3: Final Validation** - Run existing tests to ensure cleanup didn't break functionality - Verify documentation accuracy with a final review - Ensure bug fix is ready for production - Update task progress and mark completed work as you finalize the bug fix","status":"open","priority":3,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-03-19T10:33:07.356694+01:00","created_by":"Oliver Jägle","updated_at":"2026-03-19T10:33:07.356694+01:00","dependencies":[{"issue_id":"ade-4.5","depends_on_id":"ade-4","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"ade-4.5","depends_on_id":"ade-4.4","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"ade-5","title":"ade: minor (development-plan-better-in-cli-explanation.md)","description":"Responsible vibe engineering session using minor workflow for ade","status":"open","priority":2,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-03-19T11:33:13.313751+01:00","created_by":"Oliver Jägle","updated_at":"2026-03-19T11:33:13.313751+01:00"} +{"id":"ade-5.1","title":"Explore","description":"Understand the problem, analyze existing patterns, and design your approach. Consider the scope and impact of the change. **STEP 1: Analyze Requirements** - If exists: Use it to understand the required changes - Otherwise: Document requirements in your task management system **STEP 2: Review Design Approach** - If exists: Respect the design approach documented in - Otherwise: Design your approach based on the problem analysis **STEP 3: Document Decisions** - Document your analysis and design decisions - Create tasks to guide implementation - Focus on analysis and design only - do not write any code yet","status":"open","priority":3,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-03-19T11:33:13.459272+01:00","created_by":"Oliver Jägle","updated_at":"2026-03-19T11:33:13.459272+01:00","dependencies":[{"issue_id":"ade-5.1","depends_on_id":"ade-5","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"ade-5.2","title":"Implement","description":"Write clean, focused code for the minor enhancement, test your changes, and prepare for commit. **STEP 1: Review Design and Requirements** - If exists: Follow your design from - Otherwise: Elaborate design options and present them to the user - If exists: Ensure the relevant requirements from are met - Otherwise: Ensure existing requirements are met based on your task context **STEP 2: Implement Changes** - Write clean, focused code for the minor enhancement - Test your changes to ensure they work correctly and don't break existing functionality **STEP 3: Prepare for Finalization** - Update task progress as needed - Prepare documentation and commit when ready","status":"open","priority":3,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-03-19T11:33:13.597501+01:00","created_by":"Oliver Jägle","updated_at":"2026-03-19T11:33:13.597501+01:00","dependencies":[{"issue_id":"ade-5.2","depends_on_id":"ade-5","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"ade-5.2","depends_on_id":"ade-5.1","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]} +{"id":"ade-5.3","title":"Finalize","description":"Ensure code quality and documentation accuracy through systematic cleanup and review. **STEP 1: Code Cleanup** Systematically clean up development artifacts: - **Remove Debug Output**: Search for and remove all temporary debug output statements used during development. Look for language-specific debug output methods (console logging, print statements, debug output functions). Remove any debugging statements that were added for development purposes. - **Review TODO/FIXME Comments**: - Address each TODO/FIXME comment by either implementing the solution or documenting why it's deferred - Remove completed TODOs - Convert remaining TODOs to proper issue tracking if needed - **Remove Debugging Code Blocks**: - Remove temporary debugging code, test code blocks, and commented-out code - Clean up any experimental code that's no longer needed - Ensure proper error handling replaces temporary debug logging **STEP 2: Documentation Review** Review and update documentation to reflect final implementation: - **Update Long-Term Memory Documents**: Based on what was actually implemented: - If exists: Update if requirements changed during development - If exists: Update if design details were refined or changed - **Compare Against Implementation**: Review documentation against actual implemented functionality - **Update Changed Sections**: Only modify documentation sections that have functional changes - **Remove Development Progress**: Remove references to development iterations, progress notes, and temporary decisions - **Focus on Final State**: Ensure documentation describes the final implemented state, not the development process - **Ask User to Review Document Updates** **STEP 3: Final Validation** - Run existing tests to ensure cleanup didn't break functionality - Verify documentation accuracy with a final review - Ensure minor enhancement is ready for delivery - Update task progress and mark completed work as you finalize the minor enhancement","status":"open","priority":3,"issue_type":"task","owner":"github@beimir.net","created_at":"2026-03-19T11:33:13.733496+01:00","created_by":"Oliver Jägle","updated_at":"2026-03-19T11:33:13.733496+01:00","dependencies":[{"issue_id":"ade-5.3","depends_on_id":"ade-5","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"ade-5.3","depends_on_id":"ade-5.2","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]} diff --git a/.beads/last-touched b/.beads/last-touched index 971c5f4..d00dfbc 100644 --- a/.beads/last-touched +++ b/.beads/last-touched @@ -1 +1 @@ -ade-4.5 +ade-5.3 diff --git a/.vibe/beads-state-ade-better-in-cli-explanation-b8jcv3.json b/.vibe/beads-state-ade-better-in-cli-explanation-b8jcv3.json new file mode 100644 index 0000000..b0b276c --- /dev/null +++ b/.vibe/beads-state-ade-better-in-cli-explanation-b8jcv3.json @@ -0,0 +1,24 @@ +{ + "conversationId": "ade-better-in-cli-explanation-b8jcv3", + "projectPath": "/Users/oliverjaegle/projects/privat/codemcp/ade", + "epicId": "ade-5", + "phaseTasks": [ + { + "phaseId": "explore", + "phaseName": "Explore", + "taskId": "ade-5.1" + }, + { + "phaseId": "implement", + "phaseName": "Implement", + "taskId": "ade-5.2" + }, + { + "phaseId": "finalize", + "phaseName": "Finalize", + "taskId": "ade-5.3" + } + ], + "createdAt": "2026-03-19T10:33:13.963Z", + "updatedAt": "2026-03-19T10:33:13.963Z" +} \ No newline at end of file diff --git a/.vibe/development-plan-better-in-cli-explanation.md b/.vibe/development-plan-better-in-cli-explanation.md new file mode 100644 index 0000000..a1e1519 --- /dev/null +++ b/.vibe/development-plan-better-in-cli-explanation.md @@ -0,0 +1,60 @@ +# Development Plan: ade (better-in-cli-explanation branch) + +*Generated on 2026-03-19 by Vibe Feature MCP* +*Workflow: [minor](https://mrsimpson.github.io/responsible-vibe-mcp/workflows/minor)* + +## Goal +Improve user guidance in the ADE CLI — add contextual introductory text to help users understand what ADE is and what each setup facet (Process, Architecture, Practices, Autonomy, Backpressure, Harnesses, Docsets) means before they make a selection. + +## Explore + +### Tasks +- [x] Read and understand current CLI structure (index.ts, setup.ts, install.ts) +- [x] Read all facet definitions (process, architecture, practices, autonomy, backpressure) +- [x] Identify all prompts where contextual guidance is missing + +### Findings +- The setup command starts with `clack.intro("ade setup")` — no explanation of what ADE is or what the wizard will do +- Facet prompts show only `facet.label` as the message — no educational context about what the facet means +- The harness prompt says "which coding agents should receive config?" — helpful but no context on what harnesses are +- The docset prompt says "deselect any you don't need" — no explanation of what docsets are used for +- The skill install confirm says only "Install N skill(s) now?" — no context on what skills are +- `index.ts` help text is minimal — no explanation of ADE's purpose + +### Phase Entrance Criteria for Implement: +- [x] All touchpoints where user guidance is missing have been identified +- [x] Content approach is clear (what to say at each step) +- [x] No ambiguity about scope (we're adding text/hints, not redesigning prompts) + +## Implement + + +### Phase Entrance Criteria: +- [x] Explore phase findings are complete +- [x] All identified touchpoints for improvement are listed +- [x] Scope is clearly defined: text additions only, no structural changes + +### Tasks +*Tasks managed via `bd` CLI* + +## Finalize + + +### Phase Entrance Criteria: +- [x] All identified touchpoints have been addressed with guidance text +- [x] Code compiles without errors +- [x] Changes look correct and consistent in tone + +### Tasks +- [ ] Squash WIP commits: `git reset --soft `. Then, create a conventional commit. In the message, first summarize the intentions and key decisions from the development plan. Then, add a brief summary of the key changes and their side effects and dependencies + +*Tasks managed via `bd` CLI* + +## Key Decisions +*Important decisions will be documented here as they are made* + +## Notes +*Additional context and observations* + +--- +*This plan is maintained by the LLM and uses beads CLI for task management. Tool responses provide guidance on which bd commands to use for task management.* From 936b4e2660669445c111b1a1d5797b68b44d621e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oliver=20J=C3=A4gle?= Date: Thu, 19 Mar 2026 11:35:22 +0100 Subject: [PATCH 2/3] WIP: transition to finalize --- ...elopment-plan-better-in-cli-explanation.md | 6 +++- packages/cli/src/commands/setup.ts | 30 +++++++++++++++++++ packages/cli/src/index.ts | 17 ++++++++++- 3 files changed, 51 insertions(+), 2 deletions(-) diff --git a/.vibe/development-plan-better-in-cli-explanation.md b/.vibe/development-plan-better-in-cli-explanation.md index a1e1519..b3742dd 100644 --- a/.vibe/development-plan-better-in-cli-explanation.md +++ b/.vibe/development-plan-better-in-cli-explanation.md @@ -51,7 +51,11 @@ Improve user guidance in the ADE CLI — add contextual introductory text to hel *Tasks managed via `bd` CLI* ## Key Decisions -*Important decisions will be documented here as they are made* +- Used `clack.note()` for the ADE intro (boxed, titled) to make it stand out as orientation content vs. action prompts +- Used `clack.log.info()` before each facet/section prompt — lightweight, doesn't interrupt the flow, provides context without being intrusive +- Facet descriptions from the catalog data model are reused directly (they were already well-written) rather than duplicated elsewhere +- Harness guidance explicitly calls out the 'universal' option since it's the most common default and its purpose isn't obvious from the name alone +- Skill install context placed immediately before the confirm prompt so it reads naturally in sequence ## Notes *Additional context and observations* diff --git a/packages/cli/src/commands/setup.ts b/packages/cli/src/commands/setup.ts index d378f58..d59c84f 100644 --- a/packages/cli/src/commands/setup.ts +++ b/packages/cli/src/commands/setup.ts @@ -28,6 +28,20 @@ export async function runSetup( ): Promise { clack.intro("ade setup"); + clack.note( + [ + "ADE organizes the information your coding agent needs into three layers:", + "", + " Process — structured workflows that enforce how the agent tackles tasks", + " Conventions — architecture and practice skills encoding your team's decisions", + " Documentation — reference knowledge surfaced when it is relevant", + "", + "This wizard selects the right building blocks for your project and generates", + "the configuration files your coding agent will read." + ].join("\n"), + "What is ADE?" + ); + const existingConfig = await readUserConfig(projectRoot); const existingChoices = existingConfig?.choices ?? {}; @@ -56,6 +70,8 @@ export async function runSetup( const visibleFacet = { ...facet, options: visibleOptions }; + clack.log.info(facet.description); + if (facet.multiSelect) { const selected = await promptMultiSelect(visibleFacet, existingChoices); if (typeof selected === "symbol") { @@ -82,6 +98,10 @@ export async function runSetup( let excludedDocsets: string[] | undefined; if (impliedDocsets.length > 0) { + clack.log.info( + "Documentation — reference material committed to your repo and surfaced by skills when relevant.\n" + + "Deselect any libraries you are not using." + ); const selected = await clack.multiselect({ message: "Documentation — deselect any you don't need", options: impliedDocsets.map((d) => ({ @@ -119,6 +139,12 @@ export async function runSetup( allHarnessWriters.some((w) => w.id === h) ); + clack.log.info( + "Harnesses — ADE generates configuration files for each coding agent you use.\n" + + "Select all agents that should receive the generated config.\n" + + "The 'universal' harness creates an AGENTS.md that works with any agent." + ); + const selectedHarnesses = await clack.multiselect({ message: "Harnesses — which coding agents should receive config?", options: harnessOptions, @@ -173,6 +199,10 @@ export async function runSetup( } if (logicalConfig.skills.length > 0) { + clack.log.info( + "Skills — reusable instruction modules the agent invokes on demand.\n" + + "They encode your conventions so the agent applies them at the right moment." + ); const confirmInstall = await clack.confirm({ message: `Install ${logicalConfig.skills.length} skill(s) now?`, initialValue: true diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts index de4912e..da1d2ad 100644 --- a/packages/cli/src/index.ts +++ b/packages/cli/src/index.ts @@ -31,7 +31,22 @@ if (command === "setup") { console.log(version); } else { const allIds = getHarnessIds(); - console.log(`ade v${version}`); + console.log(`ade v${version} — Agentic Development Environment`); + console.log(); + console.log( + "ADE organizes the information a coding agent needs into three layers:" + ); + console.log( + " Process — structured workflows that enforce how the agent tackles tasks" + ); + console.log( + " Conventions — architecture and practice skills that encode your team's decisions" + ); + console.log( + " Documentation — reference knowledge surfaced at the moment it is relevant" + ); + console.log(); + console.log("Run `ade setup` to configure these layers for your project."); console.log(); console.log("Usage: ade [options]"); console.log(); From 35976d3b6a8e35b23c71fc66a2ce50a718923268 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oliver=20J=C3=A4gle?= Date: Thu, 19 Mar 2026 14:27:18 +0100 Subject: [PATCH 3/3] feat(cli): add user guidance and logo to setup wizard MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Users running `ade setup` had no context for what the tool does or what each facet means. The wizard felt like a blind questionnaire. This commit adds orientation at every step so that first-time users understand the purpose of each choice. - ASCII art logo (ANSI Shadow, "ADE Setup") displayed at the start of `ade setup`, before the clack intro - Opening note rewritten to explain the team-oriented purpose: pick facets, ADE translates them into a shared information hierarchy in the repo - Facet descriptions are now part of the prompt message itself (`label — description`) instead of a disconnected `log.info` line before it - Harness prompt description folded into the multiselect message — eliminates the duplicate header that appeared as a separate log entry - Skills confirm prompt now lists the individual skill names instead of showing a generic explanation followed by a bare count - Catalog facet descriptions improved for clarity: process, practices, backpressure, autonomy options reworded and reordered (sensible-defaults first as the recommended default) - Test mocks updated to include `note: vi.fn()` required by the new `clack.note()` call --- .../commands/conventions.integration.spec.ts | 1 + .../src/commands/install.integration.spec.ts | 1 + .../commands/knowledge.integration.spec.ts | 1 + .../src/commands/setup.integration.spec.ts | 2 + packages/cli/src/commands/setup.spec.ts | 3 +- packages/cli/src/commands/setup.ts | 69 ++++++++++--------- packages/cli/src/index.ts | 12 +--- packages/core/src/catalog/catalog.spec.ts | 2 +- packages/core/src/catalog/facets/autonomy.ts | 18 ++--- .../core/src/catalog/facets/backpressure.ts | 2 +- packages/core/src/catalog/facets/practices.ts | 3 +- packages/core/src/catalog/facets/process.ts | 2 +- 12 files changed, 60 insertions(+), 56 deletions(-) diff --git a/packages/cli/src/commands/conventions.integration.spec.ts b/packages/cli/src/commands/conventions.integration.spec.ts index a139bcd..8556c10 100644 --- a/packages/cli/src/commands/conventions.integration.spec.ts +++ b/packages/cli/src/commands/conventions.integration.spec.ts @@ -6,6 +6,7 @@ import { join } from "node:path"; vi.mock("@clack/prompts", () => ({ intro: vi.fn(), outro: vi.fn(), + note: vi.fn(), select: vi.fn(), multiselect: vi.fn(), confirm: vi.fn().mockResolvedValue(true), diff --git a/packages/cli/src/commands/install.integration.spec.ts b/packages/cli/src/commands/install.integration.spec.ts index 9eceb85..5f7fab2 100644 --- a/packages/cli/src/commands/install.integration.spec.ts +++ b/packages/cli/src/commands/install.integration.spec.ts @@ -7,6 +7,7 @@ import { join } from "node:path"; vi.mock("@clack/prompts", () => ({ intro: vi.fn(), outro: vi.fn(), + note: vi.fn(), log: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, select: vi.fn(), multiselect: vi.fn(), diff --git a/packages/cli/src/commands/knowledge.integration.spec.ts b/packages/cli/src/commands/knowledge.integration.spec.ts index 23da09b..78e5409 100644 --- a/packages/cli/src/commands/knowledge.integration.spec.ts +++ b/packages/cli/src/commands/knowledge.integration.spec.ts @@ -6,6 +6,7 @@ import { join } from "node:path"; vi.mock("@clack/prompts", () => ({ intro: vi.fn(), outro: vi.fn(), + note: vi.fn(), select: vi.fn(), multiselect: vi.fn(), confirm: vi.fn(), diff --git a/packages/cli/src/commands/setup.integration.spec.ts b/packages/cli/src/commands/setup.integration.spec.ts index fc3cda5..53f4799 100644 --- a/packages/cli/src/commands/setup.integration.spec.ts +++ b/packages/cli/src/commands/setup.integration.spec.ts @@ -7,11 +7,13 @@ import { join } from "node:path"; vi.mock("@clack/prompts", () => ({ intro: vi.fn(), outro: vi.fn(), + note: vi.fn(), select: vi.fn(), multiselect: vi.fn(), confirm: vi.fn(), isCancel: vi.fn().mockReturnValue(false), cancel: vi.fn(), + log: { info: vi.fn(), warn: vi.fn() }, spinner: vi.fn().mockReturnValue({ start: vi.fn(), stop: vi.fn() }) })); diff --git a/packages/cli/src/commands/setup.spec.ts b/packages/cli/src/commands/setup.spec.ts index 97d0cae..cfec287 100644 --- a/packages/cli/src/commands/setup.spec.ts +++ b/packages/cli/src/commands/setup.spec.ts @@ -6,6 +6,7 @@ import type { Catalog, LogicalConfig } from "@codemcp/ade-core"; vi.mock("@clack/prompts", () => ({ intro: vi.fn(), outro: vi.fn(), + note: vi.fn(), select: vi.fn(), multiselect: vi.fn(), confirm: vi.fn(), @@ -298,7 +299,7 @@ describe("runSetup", () => { expect(clack.multiselect).toHaveBeenCalledTimes(1); expect(clack.multiselect).toHaveBeenCalledWith( expect.objectContaining({ - message: expect.stringContaining("Harnesses") + message: expect.stringContaining("coding agents") }) ); }); diff --git a/packages/cli/src/commands/setup.ts b/packages/cli/src/commands/setup.ts index d59c84f..8944bca 100644 --- a/packages/cli/src/commands/setup.ts +++ b/packages/cli/src/commands/setup.ts @@ -26,20 +26,34 @@ export async function runSetup( projectRoot: string, catalog: Catalog ): Promise { - clack.intro("ade setup"); - + let lineIndex = 0; + const LOGO_LINES = [ + "\n", + " █████╗ ██████╗ ███████╗ ███████╗███████╗████████╗██╗ ██╗██████╗ ", + "██╔══██╗██╔══██╗██╔════╝ ██╔════╝██╔════╝╚══██╔══╝██║ ██║██╔══██╗", + "███████║██║ ██║█████╗ ███████╗█████╗ ██║ ██║ ██║██████╔╝", + "██╔══██║██║ ██║██╔══╝ ╚════██║██╔══╝ ██║ ██║ ██║██╔═══╝ ", + "██║ ██║██████╔╝███████╗ ███████║███████╗ ██║ ╚██████╔╝██║ ", + "╚═╝ ╚═╝╚═════╝ ╚══════╝ ╚══════╝╚══════╝ ╚═╝ ╚═════╝ ╚═╝ ", + "\n" + ]; + for (const line of LOGO_LINES) { + lineIndex++; + if (lineIndex === 1) { + clack.intro(line); + } else { + console.log(`│ ${line}`); + } + } clack.note( [ - "ADE organizes the information your coding agent needs into three layers:", - "", - " Process — structured workflows that enforce how the agent tackles tasks", - " Conventions — architecture and practice skills encoding your team's decisions", - " Documentation — reference knowledge surfaced when it is relevant", + "You're about to define how your team works with coding agents.", "", - "This wizard selects the right building blocks for your project and generates", - "the configuration files your coding agent will read." + "Pick your facets — architecture, practices, process — and ADE", + "translates them into a shared information hierarchy your agents", + "read from the repo. One setup, consistent across the whole team." ].join("\n"), - "What is ADE?" + "ADE — Agentic Development Environment" ); const existingConfig = await readUserConfig(projectRoot); @@ -70,8 +84,6 @@ export async function runSetup( const visibleFacet = { ...facet, options: visibleOptions }; - clack.log.info(facet.description); - if (facet.multiSelect) { const selected = await promptMultiSelect(visibleFacet, existingChoices); if (typeof selected === "symbol") { @@ -98,12 +110,9 @@ export async function runSetup( let excludedDocsets: string[] | undefined; if (impliedDocsets.length > 0) { - clack.log.info( - "Documentation — reference material committed to your repo and surfaced by skills when relevant.\n" + - "Deselect any libraries you are not using." - ); const selected = await clack.multiselect({ - message: "Documentation — deselect any you don't need", + message: + "Documentation sources — Those will be pulled to your local disk for browsing on demand", options: impliedDocsets.map((d) => ({ value: d.id, label: d.label, @@ -139,14 +148,10 @@ export async function runSetup( allHarnessWriters.some((w) => w.id === h) ); - clack.log.info( - "Harnesses — ADE generates configuration files for each coding agent you use.\n" + - "Select all agents that should receive the generated config.\n" + - "The 'universal' harness creates an AGENTS.md that works with any agent." - ); - const selectedHarnesses = await clack.multiselect({ - message: "Harnesses — which coding agents should receive config?", + message: + "Which coding agents should receive config?\n" + + "ADE generates config files for each agent you select.\n", options: harnessOptions, initialValues: validExistingHarnesses && validExistingHarnesses.length > 0 @@ -199,12 +204,14 @@ export async function runSetup( } if (logicalConfig.skills.length > 0) { - clack.log.info( - "Skills — reusable instruction modules the agent invokes on demand.\n" + - "They encode your conventions so the agent applies them at the right moment." - ); + const skillNames = logicalConfig.skills + .map((s) => ` • ${s.name}`) + .join("\n"); const confirmInstall = await clack.confirm({ - message: `Install ${logicalConfig.skills.length} skill(s) now?`, + message: + `Install ${logicalConfig.skills.length} skill(s) now?\n` + + skillNames + + `\nYou can also install them later with:\n npx @codemcp/skills experimental_install`, initialValue: true }); @@ -273,7 +280,7 @@ function promptSelect( const initialValue = getValidInitialValue(facet, existingChoices); return clack.select({ - message: facet.label, + message: `${facet.label} — ${facet.description}`, options, ...(initialValue !== undefined && { initialValue }) }); @@ -292,7 +299,7 @@ function promptMultiSelect( const initialValues = getValidInitialValues(facet, existingChoices); return clack.multiselect({ - message: facet.label, + message: `${facet.label} — ${facet.description}`, options, required: false, ...(initialValues !== undefined && { initialValues }) diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts index da1d2ad..f343a2e 100644 --- a/packages/cli/src/index.ts +++ b/packages/cli/src/index.ts @@ -34,19 +34,11 @@ if (command === "setup") { console.log(`ade v${version} — Agentic Development Environment`); console.log(); console.log( - "ADE organizes the information a coding agent needs into three layers:" + "Define how your team works with coding agents — pick your facets," ); console.log( - " Process — structured workflows that enforce how the agent tackles tasks" + "ADE translates them into a shared information hierarchy in your repo." ); - console.log( - " Conventions — architecture and practice skills that encode your team's decisions" - ); - console.log( - " Documentation — reference knowledge surfaced at the moment it is relevant" - ); - console.log(); - console.log("Run `ade setup` to configure these layers for your project."); console.log(); console.log("Usage: ade [options]"); console.log(); diff --git a/packages/core/src/catalog/catalog.spec.ts b/packages/core/src/catalog/catalog.spec.ts index c502acb..055ee46 100644 --- a/packages/core/src/catalog/catalog.spec.ts +++ b/packages/core/src/catalog/catalog.spec.ts @@ -470,8 +470,8 @@ describe("catalog", () => { expect(autonomy!.required).toBe(false); expect(autonomy!.multiSelect).toBe(false); expect(autonomy!.options.map((option) => option.id)).toEqual([ - "rigid", "sensible-defaults", + "rigid", "max-autonomy" ]); }); diff --git a/packages/core/src/catalog/facets/autonomy.ts b/packages/core/src/catalog/facets/autonomy.ts index d42f5ef..e685e37 100644 --- a/packages/core/src/catalog/facets/autonomy.ts +++ b/packages/core/src/catalog/facets/autonomy.ts @@ -9,26 +9,26 @@ export const autonomyFacet: Facet = { multiSelect: false, options: [ { - id: "rigid", - label: "Rigid", + id: "sensible-defaults", + label: "Sensible defaults", description: - "Keep built-in capabilities approval-gated and require confirmation before acting", + "Allow a curated built-in capabilities set while keeping potentially risky actions approval-gated", recipe: [ { writer: "permission-policy", - config: { profile: "rigid" } + config: { profile: "sensible-defaults" } } ] }, { - id: "sensible-defaults", - label: "Sensible defaults", + id: "rigid", + label: "Rigid", description: - "Allow a curated low-risk built-in capability set while keeping web access approval-gated", + "Keep built-in capabilities approval-gated and require confirmation before acting", recipe: [ { writer: "permission-policy", - config: { profile: "sensible-defaults" } + config: { profile: "rigid" } } ] }, @@ -36,7 +36,7 @@ export const autonomyFacet: Facet = { id: "max-autonomy", label: "Max autonomy", description: - "Allow broad local built-in autonomy while keeping web access approval-gated", + "Allow broad local built-in autonomy. Recommended for sandboxed environments only", recipe: [ { writer: "permission-policy", diff --git a/packages/core/src/catalog/facets/backpressure.ts b/packages/core/src/catalog/facets/backpressure.ts index d03f4b3..afac3a1 100644 --- a/packages/core/src/catalog/facets/backpressure.ts +++ b/packages/core/src/catalog/facets/backpressure.ts @@ -89,7 +89,7 @@ export const backpressureFacet: Facet = { id: "backpressure", label: "Backpressure", description: - "Install git hooks that enforce quality gates — silent on success, surface only relevant failures", + "Which automated quality gates to put in place. Translates to git hooks", required: false, multiSelect: true, dependsOn: ["architecture"], diff --git a/packages/core/src/catalog/facets/practices.ts b/packages/core/src/catalog/facets/practices.ts index 51d1ef9..f454c99 100644 --- a/packages/core/src/catalog/facets/practices.ts +++ b/packages/core/src/catalog/facets/practices.ts @@ -3,8 +3,7 @@ import type { Facet } from "../../types.js"; export const practicesFacet: Facet = { id: "practices", label: "Practices", - description: - "Composable development practices — mix and match regardless of stack", + description: "Development practices — mix and match regardless of stack", required: false, multiSelect: true, options: [ diff --git a/packages/core/src/catalog/facets/process.ts b/packages/core/src/catalog/facets/process.ts index 4274c3d..3ac2ba2 100644 --- a/packages/core/src/catalog/facets/process.ts +++ b/packages/core/src/catalog/facets/process.ts @@ -3,7 +3,7 @@ import type { Facet } from "../../types.js"; export const processFacet: Facet = { id: "process", label: "Process", - description: "How your AI agent receives and executes tasks", + description: "How will you guide your agent", required: true, options: [ {