generated from coulomb/repo-seed
225 lines
6.3 KiB
Markdown
225 lines
6.3 KiB
Markdown
---
|
|
id: MKTT-WP-0017
|
|
type: workplan
|
|
title: "CLI/API Polish And Practical Adoption"
|
|
domain: markitect
|
|
status: done
|
|
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: done
|
|
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.
|
|
|
|
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
|
|
- small, typical, and large contract/form-state validation flows
|
|
- small, typical, and large transform/compose/include flows
|
|
- workflow inspect/plan and backend refresh-planning flows
|
|
- large local cache/index/search performance smoke
|
|
|
|
## P17.6 - Run coverage and performance iteration
|
|
|
|
```task
|
|
id: MKTT-WP-0017-T006
|
|
status: done
|
|
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.
|
|
|
|
Implementation adds `docs/performance-notes.md` and a portable smoke test with
|
|
generous bounds for local index build and indexed search. Full-suite validation
|
|
is run before closing the workplan.
|
|
|
|
## P17.7 - Improve first-use accessibility
|
|
|
|
```task
|
|
id: MKTT-WP-0017-T007
|
|
status: done
|
|
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.
|
|
|
|
Implementation adds:
|
|
|
|
- `docs/getting-started.md`
|
|
- `docs/command-cheatsheet.md`
|
|
- `docs/examples-index.md`
|
|
- `docs/performance-notes.md`
|
|
- README and intent links to the practical docs
|
|
|
|
## 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.
|