wantsong
/
the-mindscape-of-bro-tsong
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
the-mindscape-of-bro-tsong/docs/WORKFLOW.md

7.7 KiB
Raw Blame History

Workflow

1. Model Extraction Workflow

For detailed model extraction gates, see docs/MODEL_EXTRACTION_WORKFLOW.md.

The project follows this flow:

Original article / representative text
-> source article record
-> source evidence excerpts
-> human-readable model card
-> machine-readable model JSON
-> regression cases
-> selector examples
-> validation report

2. Development Workflow

For each task:

  1. Read README.md and AGENTS.md.
  2. Check docs/PROJECT_BRIEF.md.
  3. Modify the smallest necessary set of files.
  4. Keep JSON and Markdown versions consistent.
  5. Run or update validation.
  6. Update reports or handoff notes.
  7. Do not expand scope without confirmation.

3. Model Addition Workflow

When adding a new model:

  1. Create a model JSON file in models/.
  2. Create a human-readable card in cards/.
  3. Add source article records.
  4. Add source evidence excerpts.
  5. Add regression cases.
  6. Add selector examples if relevant.
  7. Run python scripts\rebuild_indexes.py --write.
  8. Run validation.
  9. Update documentation.

4. Stabilization Workflow

If a model is unstable:

  1. Mark needs_stabilization: true.
  2. Add risks in stability_profile.main_risks.
  3. Add boundary and misuse regression cases.
  4. Do not upgrade to stability level A until tests pass.

5. Handoff Workflow

For ChatGPT-specific handoff rules, see docs/CHATGPT_HANDOFF_RULES.md.

At the end of each work session:

  1. Summarize what changed.
  2. List created and modified files.
  3. Record validation status.
  4. Separate assumptions from verified facts.
  5. List questions that require product or CCRA judgment.
  6. Suggest the smallest useful next tasks.

If the owner is going from Codex to ChatGPT, create a reports/ChatGPT交接文档_<topic>_<YYYY-MM-DD>.md file before ending the work session.

Before handoff, run:

python scripts\rebuild_indexes.py --check
python scripts\validate_model_library.py

5.1 Review Bundle Zip Workflow

When creating optional raw changed-file zips for GPT / CCRA review bundles, use the installed bundle-zip Skill instead of ad hoc PowerShell or Python compression.

Required properties:

  1. Provide an explicit file list.
  2. Use the repository root marker, for example the-mindscape-of-bro-tsong.
  3. Preserve source-relative paths inside the zip.
  4. Verify the zip by reading it back.
  5. Keep the bundle-zip JSON summary with the review bundle when useful.

Do not use Compress-Archive for review raw zips where directory paths matter; it can flatten file-list paths.

5.2 Local CCRA Review Workflow

Local CCRA review is a file-first first-pass review loop inside this project.

Use:

local_ccra_reviews/<public-round>/<local-pass>/

Examples:

local_ccra_reviews/round-05_selector-calibration-policy/01/
local_ccra_reviews/round-05_selector-calibration-policy/02/
local_ccra_reviews/round-04/pilot-01/
local_ccra_reviews/round-04/pilot-02/
local_ccra_reviews/round-03.2a_depth-limiting-qpi-override-patch/01/

Workflow:

  1. Owner decides whether the public round needs Local CCRA review.
  2. Codex creates the next numbered local review run directory.
  3. Codex writes run-notes.md, review-metadata.json, gate-manifest.yaml, and lifecycle-guard-config.yaml.
  4. Codex declares Local CCRA v0.1.2 helper policies: bundle_audit_profile, gate_execution_mode, routing_diff_policy, and lifecycle_scan_scope.
  5. Codex runs review-context-builder and applicable helper Skills, recording skipped helpers in run-notes.md.
  6. Codex writes agent-invocation-packet.md, prompt-to-send.md, and turn-prompts/.
  7. Codex invokes CCPE Agent Runtime / Codex child thread as ccra-local-reviewer.
  8. The runtime child session id or carrier id is recorded in run-notes.md.
  9. review_turn writes 04_LOCAL_CCRA_REVIEW_REPORT.md and returned-output.md.
  10. planning_turn continues the same child session and writes next-review-requirements.md when next-review planning is needed.
  11. Owner records accepted, rejected, deferred, or escalated findings in owner-decision.md.
  12. Codex executes accepted actions in the main project session.
  13. A follow-up Local CCRA review uses the next local pass label, such as 02/.
  14. After Local CCRA and Owner acceptance, Codex creates the formal Web CCRA bundle under ccra_review_bundle/round-NN_YYYY-MM-DD_topic/.

Rules:

  • Local CCRA output is formal local first review, not Owner approval and not Web CCRA approval.
  • ccra-local-reviewer is read-only and must not modify product files.
  • Review inputs and outputs should be exchanged through local files, not chat summaries.
  • Runtime child session id and continuation state belong in run-notes.md and agent-invocation-packet.md.
  • The default formal pattern is same-child review_turn followed by planning_turn.
  • Patch or post-patch review material requires routing_diff_policy: required or a manually documented equivalent table.
  • gate_execution_mode: dry_run cannot support validation pass claims.
  • Formal Web CCRA bundles exclude 04_LOCAL_CCRA_REVIEW_REPORT.md by default.
  • Include the local report in Web CCRA upload packages only when the owner explicitly asks for Web CCRA to review local findings.
  • CCPE owns the Agent Spec, Runtime Spec, invocation protocol, review rubric, and companion-capability classification.
  • Full Round-level automation is a separate workflow/orchestrator design topic, not part of the Local CCRA reviewer contract.
  • skills-vault receives a request only after CCPE or the owner decides that a companion operation is reusable deterministic automation.

6. Supplier Request Workflow

When this repository needs a capability owned by a neighboring repository:

  1. Classify the need.
  2. Use requirements/ccpe/ for expert-agent, runtime, model-governance, invocation, evaluation, or integration-registration needs.
  3. Use requirements/skills-vault/ for deterministic automation, reusable scripts, validation helpers, extraction helpers, or installable Skill needs.
  4. Write one request file per missing capability.
  5. Pause the dependent model extraction or implementation step unless the project owner explicitly says to solve the need locally.
  6. Resume after the supplier artifact, installed Skill, or owner decision is available.

7. Duplex Model Extraction Workflow

Model extraction has two concurrent tracks:

Workflow/tooling track -> request or build the process and supporting capabilities.
Content-processing track -> use available capabilities to extract, validate, and stabilize models.

Do not let the content-processing track silently absorb missing tooling work.

If a tool gap appears, record it as a supplier request and stop the blocked extraction step.

8. Framework Adoption Workflow

Third-party agentic frameworks such as CrewAI or LangGraph may be introduced only for concrete product implementation.

Before adoption:

  1. Record the product reason.
  2. Identify whether CCPE needs to supply an Agent Spec, Runtime Spec, authority rule, evaluation rule, or integration registration.
  3. Identify whether skills-vault needs to supply reusable deterministic helpers.
  4. Keep framework adapters, state, deployment, and product-specific behavior in this repository.
  5. Record the boundary decision in docs/DECISIONS.md.

9. Knowledge Asset Workflow

For long-term reusable knowledge rules, see docs/KNOWLEDGE_ASSET_RULES.md.

When a rule, model map, schema explanation, workflow summary, or product context becomes stable enough to reuse across sessions, create or update a file under knowledge_assets/.

Do not leave durable knowledge only in temporary reports.

For repository-wide file identity rules, including canonical files, generated reports, review archives, and temporary files, see docs/FILE_TAXONOMY.md.