IMisbahk · IMisbahk · Aug 13, 2026 · Aug 13, 2026 · Aug 13, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,25 @@
 
 All notable changes to mstack are documented here. This project follows [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+### Added
+
+- Expand curated packs with additional specialists, skills, invokable prompts, and
+  argv-only task recipes for every starter domain.
+- Add backend/API, QA/testing, observability, and documentation packs.
+- Add `mstack pack recommend` to cite repository evidence without installing packs.
+- Add `mstack catalog --query` and `mstack task list --pack/--risk` discovery filters.
+- Enforce task file preconditions and report missing executables as step failures.
+- Add mobile, data-platform, CLI, and firmware worked examples.
+
+### Changed
+
+- Compose selected packs with first-id-wins merging so core resources cannot be
+  overwritten by a colliding pack identifier.
+- Include pack specialists, skills, and prompts in `mstack catalog`.
+- Show selected packs in `mstack status`.
+
 ## [0.6.0] - 2026-07-25
 
 ### Added

diff --git a/README.md b/README.md
@@ -82,7 +82,7 @@ Use `mstack catalog` to discover the installed engineering resources and `mstack
 
 From a clean `main` checkout, run `./script.sh major`, `./script.sh minor`, or `./script.sh patch`. The script validates the package, updates all workspace versions, regenerates the command reference, runs the release checks, creates and pushes the `mstack-v<version>` commit and tag, then opens npm's web login when needed and publishes `@imisbahk/mstack`. If publishing fails after the git push, rerun the printed `npm publish` command; do not create another version.
 
-The current platform includes 15 AI environments, 19 specialist agents, 20 reusable skills, 4 automation hooks, 19 prompt packs, and 10 runtime templates. Its ten-phase workflow runs bounded specialist lanes in parallel where the AI environment supports subagents, while preserving one decision owner and safe sequential fallbacks elsewhere. It supports npm, pnpm, Yarn, and Bun, with versioned JSON output for automation.
+The current platform includes 15 AI environments, 19 specialist agents, 20 reusable skills, 4 automation hooks, 19 prompt packs, 10 runtime templates, 14 curated capability packs, and policy-gated task recipes. Its ten-phase workflow runs bounded specialist lanes in parallel where the AI environment supports subagents, while preserving one decision owner and safe sequential fallbacks elsewhere. It supports npm, pnpm, Yarn, and Bun, with versioned JSON output for automation.
 
 Projects such as [g-stack](https://github.com/garrytan/gstack) already approach AI development environments with broad capability and configuration. I respect that approach. Build Like This makes a different trade-off: fewer choices, stronger defaults, and a specific product-to-production workflow. The purpose of mstack is not to expose every possible setup. It is to get a repository ready for the process I would personally use.
 
@@ -141,6 +141,10 @@ Each example begins with product and architecture documents. There is no impleme
 - [SaaS: InvoiceFlow](examples/saas/README.md) — design tenancy, payments, and operational reliability before they become incidents.
 - [Startup: CareCircle](examples/startup/README.md) — validate risky assumptions before automating the business.
 - [Web application: LocalBoard](examples/web-app/README.md) — keep a conventional application simple and modular.
+- [Mobile application: FieldNote](examples/mobile-app/README.md) — treat permissions, offline queues, and store constraints as product decisions.
+- [Data platform: SignalWell](examples/data-platform/README.md) — make data contracts, late events, and evaluation part of architecture.
+- [CLI tool: RepoLens](examples/cli-tool/README.md) — keep command contracts stable, safe, and automation-friendly.
+- [Firmware device: DockSense](examples/firmware-device/README.md) — keep hardware fail-safes explicit and bench claims evidence-gated.
 
 ## AI agents in this repository
 

diff --git a/docs/architecture.md b/docs/architecture.md
@@ -58,4 +58,4 @@ Start from [`templates/architecture.template.md`](../templates/architecture.temp
 
 ## Current mstack architecture decision
 
-Capability packs are a curated in-process registry in the CLI. Each pack declares metadata, a normal `IntegrationSpec` contribution, and declarative argv-only task recipes. `ai setup` composes the core spec with manifest-selected packs, then uses existing adapters, planner, reconciliation, and ownership mechanisms. The project manifest stores the desired pack ID/version set; runtime manifests continue to own rendered files. Tasks execute literal argument vectors with `shell: false`, apply the configured policy before execution, and emit per-step results. See [ADR-0003](decisions/0003-curated-capability-packs-and-task-recipes.md).
+Capability packs are a curated in-process registry in the CLI. Each pack declares metadata, a normal `IntegrationSpec` contribution, and declarative argv-only task recipes. `ai setup` composes the core spec with manifest-selected packs, then uses existing adapters, planner, reconciliation, and ownership mechanisms. Composition is first-id-wins so core resources are never overwritten by a pack with a colliding identifier. The project manifest stores the desired pack ID/version set; runtime manifests continue to own rendered files. Tasks execute literal argument vectors with `shell: false`, apply file preconditions and the configured policy before execution, and emit per-step results. `pack recommend` reads well-known marker files only and does not write. See [ADR-0003](decisions/0003-curated-capability-packs-and-task-recipes.md).
diff --git a/docs/cli/README.md b/docs/cli/README.md
@@ -48,7 +48,10 @@ Existing planning documents are preserved. `--force` is the only path that inten
 | `mstack explain` | Walk through the repository's installed workflow |
 | `mstack ai setup` | Configure detected or selected AI coding runtimes |
 | `mstack ai list` | Inspect runtime support and detection |
-| `mstack catalog` | Discover agents, skills, prompts, hooks, and templates |
+| `mstack catalog` | Discover agents, skills, prompts, hooks, templates, packs, and task recipes |
+| `mstack pack` | List, inspect, recommend, add, and remove curated capability packs |
+| `mstack task` | Inspect and run policy-gated argv-only task recipes |
+| `mstack agent` | List installed specialists and runtime invocation guidance |
 | `mstack validate` | Verify planning readiness, ownership, and runtime integrity |
 | `mstack doctor` | Diagnose runtime, repository, permissions, and manifest health |
 | `mstack config` | Inspect or change layered configuration |

diff --git a/docs/cli/command-reference.md b/docs/cli/command-reference.md
@@ -21,8 +21,8 @@ Commands:
                                   invocation guidance; does not execute models
   ai                              configure AI coding environments for this
                                   repository
-  catalog [options] [kind]        discover agents, skills, prompts, hooks, and
-                                  templates
+  catalog [options] [kind]        discover packs, agents, skills, prompts,
+                                  hooks, templates, and task recipes
   config                          inspect or change mstack configuration
   doctor [options]                inspect the runtime and current project
   explain [options]               walk through Misbah's Build Like This workflow
@@ -172,15 +172,17 @@ Options:
 ```text
 Usage: mstack catalog [options] [kind]
 
-discover agents, skills, prompts, hooks, and templates
+discover packs, agents, skills, prompts, hooks, templates, and task recipes
 
 Arguments:
-  kind        limit results to one resource kind (choices: "packs", "agents",
-              "skills", "prompts", "hooks", "templates", "task-recipes")
+  kind            limit results to one resource kind (choices: "packs",
+                  "agents", "skills", "prompts", "hooks", "templates",
+                  "task-recipes")
 
 Options:
-  -h, --help  display help for command
-  --json      print a versioned JSON catalog (default: false)
+  -h, --help      display help for command
+  --json          print a versioned JSON catalog (default: false)
+  --query <text>  filter by id, description, or pack
 ```
 
 ## mstack pack
@@ -199,6 +201,8 @@ Commands:
   help [command]             display help for command
   info [options] <id>        show pack resources and prerequisites
   list [options]             show curated packs
+  recommend [options]        suggest curated packs from repository evidence
+                             without installing them
   remove [options] <ids...>  remove selected packs and reconcile owned runtime
                              files
   update [options]           reconcile selected packs through ai setup
@@ -228,6 +232,18 @@ Options:
   --json      print a versioned JSON result (default: false)
 ```
 
+## mstack pack recommend
+
+```text
+Usage: mstack pack recommend [options]
+
+suggest curated packs from repository evidence without installing them
+
+Options:
+  -h, --help  display help for command
+  --json      print a versioned JSON result (default: false)
+```
+
 ## mstack pack add
 
 ```text
@@ -309,8 +325,11 @@ Usage: mstack task list [options]
 list task recipes
 
 Options:
-  -h, --help  display help for command
-  --json      print a versioned JSON result (default: false)
+  -h, --help      display help for command
+  --json          print a versioned JSON result (default: false)
+  --pack <id>     limit results to one pack
+  --risk <class>  limit results to one risk class (choices: "read-only",
+                  "working-tree", "destructive", "remote")
 ```
 
 ## mstack task show

diff --git a/docs/decisions/0003-curated-capability-packs-and-task-recipes.md b/docs/decisions/0003-curated-capability-packs-and-task-recipes.md
@@ -15,5 +15,7 @@ Task recipes are data, not arbitrary shell programs: each step is a literal argv
 
 - Existing runtime adapter and reconciliation behavior remains the sole file-ownership mechanism.
 - v1 excludes third-party pack loading and high-consequence publishing/deployment recipes.
+- Pack recommendation inspects well-known marker files and does not change selection or install resources.
+- Composition is first-id-wins so a pack cannot overwrite a core resource id.
 - Pack removal changes desired selection and requires normal AI setup reconciliation to remove stale owned runtime resources safely.
 - Model execution remains visible to and controlled by the user’s chosen runtime.
diff --git a/docs/features.md b/docs/features.md
@@ -29,6 +29,6 @@ The biggest mistake I want to prevent is a feature becoming a self-justifying pr
 
 | Feature | User need | Status | Owner | Specification | Outcome metric |
 | --- | --- | --- | --- | --- | --- |
-| Extensible AI engineering packs and safe task recipes | Teams need domain-specific AI guidance and repeatable local workflows without unreviewed model execution or shell injection. | in progress | mstack maintainers | [AI engineering packs](features/ai-engineering-packs.md) | A compatible runtime renders selected packs deterministically; every non-read-only task has a recorded policy decision. |
+| Extensible AI engineering packs and safe task recipes | Teams need domain-specific AI guidance and repeatable local workflows without unreviewed model execution or shell injection. | in progress | mstack maintainers | [AI engineering packs](features/ai-engineering-packs.md) | A compatible runtime renders selected packs deterministically; every non-read-only task has a recorded policy decision; recommend cites repository evidence without installing packs. |
 
 Small, obvious work can remain in `product.md`, an issue, and tests. More documentation is not automatically more disciplined. The right documentation makes the next decision clearer.
diff --git a/docs/features/ai-engineering-packs.md b/docs/features/ai-engineering-packs.md
@@ -4,22 +4,27 @@
 
 Users of `mstack` can opt into a curated domain pack, discover its specialists and tasks, and safely run a small catalog of local argv-only task recipes. `mstack ai setup` remains the lightweight core setup and renders selected compatible packs; it does not execute models or coordinate inference.
 
-The first release includes starter packs for repository intelligence, software/web, systems, embedded/firmware, robotics, data/ML, mobile, games/graphics, infrastructure/security, and CLI/devtools. Repository intelligence produces evidence-backed maps and explanations, not autonomous code edits.
+The catalog includes starter packs for repository intelligence, software/web, systems, embedded/firmware, robotics, data/ML, mobile, games/graphics, infrastructure/security, CLI/devtools, backend/API, QA/testing, observability, and documentation. Repository intelligence produces evidence-backed maps and explanations, not autonomous code edits. `mstack pack recommend` inspects well-known repository markers and suggests packs with cited evidence; it never installs them.
+
+Every curated pack ships specialists, skills, an invokable prompt, and policy-gated task recipes. Domain recipes stay argv-only and fail before execution when declared file preconditions are missing.
 
 ## Acceptance criteria
 
-- `mstack pack list`, `info`, `add`, `remove`, and `update` expose only bundled curated packs.
+- `mstack pack list`, `info`, `add`, `remove`, `update`, and `recommend` expose only bundled curated packs.
 - Selected pack IDs and versions are persisted in the mstack manifest and are composed into normal runtime rendering.
-- `mstack catalog` includes packs and task recipes, and `mstack agent` only describes installed specialists and invocation guidance.
-- `mstack task` accepts declarative literal argv steps only, supports ordered failure-stop execution, dry run, JSON records, timeout, and policy confirmation.
+- `mstack catalog` includes packs, pack specialists, pack skills, pack prompts, and task recipes, and `mstack agent` only describes installed specialists and invocation guidance.
+- `mstack catalog --query` and `mstack task list --pack/--risk` filter the same source-backed inventory.
+- `mstack task` accepts declarative literal argv steps only, supports ordered failure-stop execution, dry run, JSON records, timeout, file preconditions, and policy confirmation.
 - Default `balanced` policy runs read-only recipes directly and requires explicit confirmation for working-tree, destructive, and remote work.
+- Duplicate pack, specialist, skill, prompt, and task IDs are rejected before a pack can be registered.
 
 ## Non-goals
 
 - Remote, npm, Git, or marketplace pack installation.
 - Hosting inference, selecting models, or autonomously dispatching agents.
 - Shell-script recipes, implicit commit/push, packaging, publishing, or deployment recipes.
+- Automatic pack installation from repository heuristics.
 
 ## Failure and recovery
 
-Unknown packs/tasks, missing initialization, declined confirmation, command errors, and timeouts fail with a location-specific result. Recipe execution stops at its first failed step. Pack removal changes desired selection; `mstack ai setup` reconciles runtime-owned artifacts under existing ownership and drift protections.
+Unknown packs/tasks, missing initialization, missing recipe preconditions, declined confirmation, missing executables, command errors, and timeouts fail with a location-specific result. Recipe execution stops at its first failed step. Pack removal changes desired selection; `mstack ai setup` reconciles runtime-owned artifacts under existing ownership and drift protections. Recommendation is read-only and does not change the manifest.
diff --git a/docs/features/cli-validation-and-catalog.md b/docs/features/cli-validation-and-catalog.md
@@ -11,7 +11,8 @@ Developers can see what the Build Like This runtime contains without inspecting
 
 Included:
 
-- `mstack catalog [kind]` for agents, skills, prompts, hooks, and templates;
+- `mstack catalog [kind]` for agents, skills, prompts, hooks, templates, packs, and task recipes;
+- `mstack catalog --query` for id and description filtering;
 - stable, versioned JSON output for catalog automation;
 - `mstack validate [directory]` for planning-document readiness, mstack manifest integrity, and AI runtime verification;
 - `--strict` validation that treats warnings as release-blocking;
@@ -30,7 +31,7 @@ Not included:
 
 ### Catalog
 
-`mstack catalog` lists every resource grouped by kind and reports exact totals. An optional kind limits output to `agents`, `skills`, `prompts`, `hooks`, or `templates`. Catalog reads the versioned runtime definitions directly, so documentation and terminal output cannot maintain a separate inventory.
+`mstack catalog` lists every resource grouped by kind and reports exact totals. An optional kind limits output to `packs`, `agents`, `skills`, `prompts`, `hooks`, `templates`, or `task-recipes`. `--query` filters those results by id, description, or pack. Catalog reads the versioned runtime definitions and the curated pack registry directly, so documentation and terminal output cannot maintain a separate inventory.
 
 ### Validation
 

diff --git a/docs/product.md b/docs/product.md
@@ -60,4 +60,4 @@ Start from [`templates/product.template.md`](../templates/product.template.md).
 
 ## Current mstack product decision
 
-For mstack users who work across different engineering domains, optional curated capability packs provide specialist guidance and safe local task recipes without making the default setup heavyweight. The boundary is intentional: mstack installs and reconciles runtime-native resources, while the selected AI runtime owns model inference and any agent coordination. See [the feature specification](features/ai-engineering-packs.md).
+For mstack users who work across different engineering domains, optional curated capability packs provide specialist guidance, invokable prompts, and safe local task recipes without making the default setup heavyweight. Pack recommendation cites repository evidence and leaves selection explicit. The boundary is intentional: mstack installs and reconciles runtime-native resources, while the selected AI runtime owns model inference and any agent coordination. See [the feature specification](features/ai-engineering-packs.md).
diff --git a/examples/cli-tool/README.md b/examples/cli-tool/README.md
@@ -0,0 +1,31 @@
+# CLI Tool Example: RepoLens
+
+RepoLens is a fictional local CLI that maps a repository's modules, entry points, and documented test commands so a developer or agent can orient without guessing.
+
+I included a CLI example because developer tools are products with contracts. Stdout, JSON, exit codes, and default safety are the user interface. A mapper that writes files, runs tests, or changes format without a version bump is a breaking change, even if the code still "works."
+
+## What this example demonstrates
+
+- treat argv, stdout, stderr, and exit codes as a versioned contract;
+- keep JSON output stable and explicit so scripts and agents can rely on it;
+- default to non-destructive, read-only behavior;
+- distinguish observed repository facts from inferred structure;
+- skip network, installs, and test execution until the user asks.
+
+## Documents before implementation
+
+1. [`product.md`](product.md) defines the local user, the map they need, and what the tool must never do by default.
+2. [`architecture.md`](architecture.md) describes command contracts, scanners, output schemas, and failure behavior.
+
+## How I would deliver it
+
+1. Watch five developers (or agents) onboard onto an unfamiliar repo and note where they guess.
+2. Define the map schema, command names, and exit codes.
+3. Implement read-only detectors for modules and test commands.
+4. Freeze `--json` fixtures before polishing human output.
+5. Add `--print-tests` display; do not execute tests in the first release.
+6. Pilot on this repository and two others with different layouts before calling the contract stable.
+
+## Suggested mstack packs
+
+Pack ids to consider later: `cli-devtools` and `repository-intelligence`. `mstack pack recommend` may cite repository evidence for them; it does not install packs. Adding a pack remains an explicit choice.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -58,4 +58,4 @@ Start from [`templates/architecture.template.md`](../templates/architecture.temp

		## Current mstack architecture decision

		Capability packs are a curated in-process registry in the CLI. Each pack declares metadata, a normal `IntegrationSpec` contribution, and declarative argv-only task recipes. `ai setup` composes the core spec with manifest-selected packs, then uses existing adapters, planner, reconciliation, and ownership mechanisms. The project manifest stores the desired pack ID/version set; runtime manifests continue to own rendered files. Tasks execute literal argument vectors with `shell: false`, apply the configured policy before execution, and emit per-step results. See [ADR-0003](decisions/0003-curated-capability-packs-and-task-recipes.md).
		Capability packs are a curated in-process registry in the CLI. Each pack declares metadata, a normal `IntegrationSpec` contribution, and declarative argv-only task recipes. `ai setup` composes the core spec with manifest-selected packs, then uses existing adapters, planner, reconciliation, and ownership mechanisms. Composition is first-id-wins so core resources are never overwritten by a pack with a colliding identifier. The project manifest stores the desired pack ID/version set; runtime manifests continue to own rendered files. Tasks execute literal argument vectors with `shell: false`, apply file preconditions and the configured policy before execution, and emit per-step results. `pack recommend` reads well-known marker files only and does not write. See [ADR-0003](decisions/0003-curated-capability-packs-and-task-recipes.md).
Original file line number	Diff line number	Diff line change
Expand Up		@@ -60,4 +60,4 @@ Start from [`templates/product.template.md`](../templates/product.template.md).

		## Current mstack product decision

		For mstack users who work across different engineering domains, optional curated capability packs provide specialist guidance and safe local task recipes without making the default setup heavyweight. The boundary is intentional: mstack installs and reconciles runtime-native resources, while the selected AI runtime owns model inference and any agent coordination. See [the feature specification](features/ai-engineering-packs.md).
		For mstack users who work across different engineering domains, optional curated capability packs provide specialist guidance, invokable prompts, and safe local task recipes without making the default setup heavyweight. Pack recommendation cites repository evidence and leaves selection explicit. The boundary is intentional: mstack installs and reconciles runtime-native resources, while the selected AI runtime owns model inference and any agent coordination. See [the feature specification](features/ai-engineering-packs.md).