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:

python3 -m venv .venv
source .venv/bin/activate
pip install -e tools/discussion-framework

After moving this directory to its own GitHub repository:

pip install "git+ssh://git@git-local.bquarkz.net:2222/Intrepid/discussion-framework.git@master"

Commands

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.