generated from coulomb/repo-seed
CLI and API polish
This commit is contained in:
212
workplans/MKTT-WP-0017-cli-api-polish-and-practical-adoption.md
Normal file
212
workplans/MKTT-WP-0017-cli-api-polish-and-practical-adoption.md
Normal file
@@ -0,0 +1,212 @@
|
||||
---
|
||||
id: MKTT-WP-0017
|
||||
type: workplan
|
||||
title: "CLI/API Polish And Practical Adoption"
|
||||
domain: markitect
|
||||
status: active
|
||||
owner: markitect-tool
|
||||
topic_slug: markitect
|
||||
planning_priority: P1
|
||||
planning_order: 40
|
||||
depends_on_workplans:
|
||||
- MKTT-WP-0003
|
||||
- MKTT-WP-0013
|
||||
related_workplans:
|
||||
- MKTT-WP-0004
|
||||
- MKTT-WP-0007
|
||||
- MKTT-WP-0008
|
||||
- MKTT-WP-0010
|
||||
- MKTT-WP-0011
|
||||
created: "2026-05-04"
|
||||
updated: "2026-05-04"
|
||||
state_hub_workstream_id: "077bc50c-360b-425a-a1ad-fd961f819422"
|
||||
---
|
||||
|
||||
# MKTT-WP-0017: CLI/API Polish And Practical Adoption
|
||||
|
||||
## Purpose
|
||||
|
||||
Polish `markitect-tool` from a broad implementation toolkit into something that
|
||||
is easy to discover, use, document, test, and adopt in practical Markdown
|
||||
pipelines.
|
||||
|
||||
This workplan intentionally pauses advanced future architecture work and focuses
|
||||
on the public surface:
|
||||
|
||||
- CLI completeness and consistency
|
||||
- shell completion and Unix-style generated command documentation
|
||||
- public API completeness and generated API documentation
|
||||
- CLI/API alignment with the extension architecture
|
||||
- usecase-driven E2E testing
|
||||
- accessibility for practical first use
|
||||
|
||||
## Decisions
|
||||
|
||||
- Treat every implemented architecture capability as something that should be
|
||||
discoverable through CLI, API, docs, and extension descriptors.
|
||||
- Keep generated docs deterministic and local-first.
|
||||
- Use web-researched practical usecases as adoption and E2E-test anchors.
|
||||
- Prefer improving command/API discoverability before adding more advanced
|
||||
features.
|
||||
|
||||
## P17.1 - Audit CLI and API surface completeness
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0017-T001
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "1827fec2-3c64-4dd0-9b24-e6a7c3a19912"
|
||||
```
|
||||
|
||||
Review all implemented modules, built-in extensions, and docs. Identify missing
|
||||
CLI accesspoints, missing public API exports, and mismatches between extension
|
||||
descriptors and real commands.
|
||||
|
||||
Initial implementation adds:
|
||||
|
||||
- `mkt completion`
|
||||
- `mkt extension list`
|
||||
- `mkt extension inspect`
|
||||
- `mkt extension commands`
|
||||
- `mkt docs cli`
|
||||
- `mkt docs api`
|
||||
- top-level API exports for newer query, backend, extension, schema, and policy
|
||||
surfaces
|
||||
|
||||
Output: implementation, tests, and an updated audit note if gaps remain.
|
||||
|
||||
## P17.2 - Provide shell completion and Unix-style command docs
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0017-T002
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "052b9684-cc23-4215-926e-bc498fe10f4f"
|
||||
```
|
||||
|
||||
Expose Bash, Zsh, and Fish completion scripts through the CLI and generate a
|
||||
Markdown command reference from the live Click tree.
|
||||
|
||||
Output: CLI command, generated `docs/cli-reference.md`, README installation
|
||||
notes, and tests.
|
||||
|
||||
## P17.3 - Provide generated API documentation
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0017-T003
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "8874078a-e2f4-4a4e-a2d0-a7cbd5d62816"
|
||||
```
|
||||
|
||||
Generate a compact public API reference from `markitect_tool.__all__` and make
|
||||
`pdoc` available as an optional richer documentation path.
|
||||
|
||||
Output: CLI command, generated `docs/api-reference.md`, optional docs extra,
|
||||
README notes, and tests.
|
||||
|
||||
## P17.4 - Compile practical usecases and relevance expectations
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0017-T004
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "23fffff4-a1f0-498c-b4d7-00241d0bb29d"
|
||||
```
|
||||
|
||||
Revisit `INTENT.md`, PRD, FRS, examples, and docs. Use web research to define a
|
||||
practical usecase matrix with relevance expectations and adoption signals.
|
||||
|
||||
Output: `docs/practical-usecase-relevance.md` and links from intent/README.
|
||||
|
||||
## P17.5 - Build E2E fixture matrix
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0017-T005
|
||||
status: in_progress
|
||||
priority: high
|
||||
state_hub_task_id: "1159ec82-00e6-45cd-8a2c-e61ae03e758a"
|
||||
```
|
||||
|
||||
Create E2E tests for the practical usecases with small, typical, and large
|
||||
variations where meaningful.
|
||||
|
||||
Required coverage:
|
||||
|
||||
- parse/AST/metrics
|
||||
- schema and contract checks
|
||||
- query/extract and indexed search
|
||||
- transform/compose/include/references/processors
|
||||
- templates/generation/functions
|
||||
- workflow inspect/plan/run
|
||||
- cache/index/refresh plans
|
||||
- policy-aware query/search
|
||||
- literate weave/tangle
|
||||
- explode/implode
|
||||
- runtime form-state
|
||||
- context packages
|
||||
- extension catalog and generated docs
|
||||
|
||||
Output: deterministic tests and fixtures with no network dependency.
|
||||
|
||||
Initial coverage has been added for:
|
||||
|
||||
- small, typical, and large synthetic corpus parse/query/cache/search/context
|
||||
package flow
|
||||
- example-backed contract, template, function, workflow, reference, processor,
|
||||
policy, literate tangle, and explode/implode flows
|
||||
|
||||
Remaining work: expand the matrix into explicit small/typical/large variants
|
||||
for every high-relevance workflow and add performance assertions where they are
|
||||
stable.
|
||||
|
||||
## P17.6 - Run coverage and performance iteration
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0017-T006
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "8dd5afe5-cefa-4388-bf4c-a975ba5c77c3"
|
||||
```
|
||||
|
||||
Run full tests repeatedly, add coverage instrumentation if needed, and fix bugs
|
||||
or performance issues exposed by the E2E matrix.
|
||||
|
||||
Output: passing test suite, documented coverage gaps, and targeted performance
|
||||
notes for large synthetic corpora.
|
||||
|
||||
## P17.7 - Improve first-use accessibility
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0017-T007
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "590af805-0cc0-4585-b85f-9e95679afa77"
|
||||
```
|
||||
|
||||
Make the first useful experience obvious.
|
||||
|
||||
Possible improvements:
|
||||
|
||||
- concise README quickstart with common workflows
|
||||
- generated examples index
|
||||
- command cheat sheet
|
||||
- install/completion instructions
|
||||
- clearer diagnostics examples
|
||||
- `mkt extension` discovery guidance
|
||||
- optional docs generation workflow using `pdoc`
|
||||
|
||||
Output: README/docs/examples polish and tests where executable.
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
- Every implemented subsystem has CLI access, public API access, docs, examples,
|
||||
and tests or a documented reason for omission.
|
||||
- Shell completion works for Bash, Zsh, and Fish through `mkt completion`.
|
||||
- `docs/cli-reference.md` and `docs/api-reference.md` can be regenerated from
|
||||
the live implementation.
|
||||
- Practical usecases are documented with relevance expectations and E2E coverage
|
||||
targets.
|
||||
- E2E tests cover small, typical, and large variations for the important
|
||||
workflows.
|
||||
- Full test suite passes.
|
||||
Reference in New Issue
Block a user