109 lines
4.1 KiB
Markdown
109 lines
4.1 KiB
Markdown
# Discussion Framework
|
|
|
|
Deterministic CLI for managing `discussion/` workflow state without spending AI
|
|
tokens on mechanical maintenance.
|
|
|
|
AI should write and review content. This CLI should manage state.
|
|
|
|
## Install
|
|
|
|
From this repository:
|
|
|
|
```bash
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -e tools/discussion-framework
|
|
```
|
|
|
|
After moving this directory to its own GitHub repository:
|
|
|
|
```bash
|
|
pip install "git+https://github.com/<org>/discussion-framework.git@v0.1.0"
|
|
```
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
discussion init
|
|
discussion start pbs-autocomplete-parameter-names "PBS autocomplete parameter names" --tag compiler-pbs --tag lsp
|
|
discussion accept-agenda DSC-0037
|
|
discussion add-decision DSC-0037 --title "Canonical PBS parameter names for editor assistance"
|
|
discussion accept-decision DSC-0037
|
|
discussion add-plan DSC-0037 --title "Propagate canonical parameter names to stdlib and LSP surfaces"
|
|
discussion mark-plan PLN-0078 in_progress
|
|
discussion mark-plan PLN-0078 done
|
|
discussion status
|
|
discussion status --json
|
|
discussion validate
|
|
discussion validate --json
|
|
discussion inspect DSC-0035
|
|
discussion inspect DSC-0035 --json
|
|
discussion context DSC-0035
|
|
discussion context DSC-0035 --json
|
|
discussion next-actions
|
|
discussion backup-index
|
|
discussion housekeep DSC-0035 --lesson discussion/lessons/.../LSN-0051-name.md
|
|
discussion housekeep DSC-0035 --no-lesson
|
|
```
|
|
|
|
Use `--root <path>` when running outside the repository root.
|
|
|
|
When a command is executed from inside the existing `discussion/` directory, the
|
|
CLI resolves the repository root to the parent directory instead of creating a
|
|
nested `discussion/discussion` tree.
|
|
|
|
## Contract
|
|
|
|
- `init` creates the canonical `discussion/` layout and `index.ndjson`.
|
|
- `start` creates a new discussion record and its first agenda artifact.
|
|
- `accept-agenda` marks an agenda as accepted once the discussion is ready for
|
|
a decision.
|
|
- `add-decision` creates a decision artifact from an accepted agenda and indexes
|
|
it under the discussion.
|
|
- `accept-decision` marks a decision as accepted once its content is normative.
|
|
- `add-plan` creates a plan artifact from an accepted decision and indexes it
|
|
under the discussion.
|
|
- `mark-plan` moves a plan through `open`, `review`, `accepted`,
|
|
`in_progress`, `done`, or `abandoned`.
|
|
- `status` prints a compact discussion overview.
|
|
- `inspect` shows one discussion and its indexed artifacts.
|
|
- `context` prints compact AI-ready context and suggested next actions.
|
|
- `next-actions` lists operational next steps across discussions.
|
|
- `validate` checks the index, counters, artifact references, and lesson files.
|
|
- `backup-index` replaces the old shell backup script by copying
|
|
`discussion/index.ndjson` into `discussion/.backups/`.
|
|
- `housekeep` marks a discussion `done`, removes workflow artifacts, clears
|
|
workflow arrays from the index, and optionally registers an existing lesson.
|
|
|
|
The command does not generate agenda, decision, plan, or lesson prose. That work
|
|
belongs to humans or AI agents.
|
|
|
|
## Codex Integration
|
|
|
|
Repository instructions and Codex skills should treat this CLI as the mechanical
|
|
state manager.
|
|
|
|
Recommended policy:
|
|
|
|
- Agents use AI for content: agenda, decision, plan, lesson, specs, and code.
|
|
- Agents use `discussion` for state: status, validation, housekeeping, index
|
|
updates, and workflow artifact pruning.
|
|
- Agents should not manually edit `discussion/index.ndjson` when an equivalent
|
|
`discussion` command exists.
|
|
- If a command is missing, agents may perform the operation manually and should
|
|
record the missing command as a framework improvement.
|
|
|
|
Recommended skill behavior:
|
|
|
|
- `discussion-status`: run `discussion status` first, then inspect files only
|
|
when the user asks for deeper analysis.
|
|
- `discussion-context`: run `discussion context DSC-XXXX`; this is the primary
|
|
AI handoff surface.
|
|
- `discussion-validate`: run `discussion validate`; manual validation is a
|
|
fallback only.
|
|
- `discussion-housekeep`: AI may decide whether a lesson is needed and write it;
|
|
final state mutation must use `discussion housekeep --lesson ...` or
|
|
`discussion housekeep --no-lesson`.
|
|
- `discussion-framework`: document the split between content generation and
|
|
deterministic state operations.
|