# AGENTS.md

## 1. Role

You are Codex working inside the `the-mindscape-of-bro-tsong` repository.

Your role is to implement the engineering structure for a file-first cognitive model library MVP.

You are not responsible for product strategy, marketing, sales, UI design, or broad feature invention.

Product planning decisions come from the project owner and CCRA / ChatGPT-side architecture work.

## 2. Project Goal

Build a minimal, file-first model library system that can represent cognitive models as:

- Human-readable Markdown model cards
- Machine-readable JSON model specs
- Source article records
- Source evidence excerpts
- Regression test cases
- Minimal model selector examples

The current phase is `model_library_mvp`.

The first sample models are:

- QPI
- Intellectual Archaeology

## 3. Core Principle

Do not overbuild.

The goal is not to create a full platform.

The goal is to create a stable model asset foundation.

Prefer:

- JSON over database
- Markdown over UI
- Explicit schema over hidden convention
- Simple scripts over complex services
- Traceability over automation
- Validation over feature expansion

## 4. Non-Goals

Do not implement:

- Full frontend application
- Backend service
- Database
- Vector database
- Full RAG system
- User accounts
- Authentication
- Payment
- Public platform
- Multi-user collaboration
- Complete knowledge graph
- Automatic extraction from all articles
- Full question-answering system

If a task seems to require one of these, stop and ask for product confirmation.

## 5. Repository Layout

Expected layout:

```text
docs/
schemas/
models/
cards/
sources/
tests/
selector/
scripts/
reports/
```

Each folder should contain a README explaining its purpose.

Do not create a nested `model_library_mvp/` directory unless the project owner explicitly changes the repository strategy.

## 6. Data Rules

Machine-readable files should use JSON.

Human-readable model cards and documentation should use Markdown.

Every model must eventually have:

- `model_id`
- `model_name`
- `model_type`
- `pipeline_position`
- `one_sentence_definition`
- `core_question`
- `core_mechanism`
- `source_articles`
- `source_evidence`
- `input_types`
- `output_types`
- `call_when`
- `do_not_call_when`
- `common_misuses`
- `failure_modes`
- `selection_priority`
- `confidence_level`
- `stability_profile`
- `regression_status`
- `productization_notes`

## 7. Source Traceability Rules

Every model should reference source article IDs.

Every model should reference source evidence excerpt IDs.

Do not invent source IDs without adding matching records in `sources/source_articles.json` or `sources/source_excerpts.json`.

If source content is not yet available, use placeholder records with clear notes such as:

```text
raw_excerpt: "待填入原文片段"
```

Do not pretend placeholder excerpts are verified evidence.

## 8. Regression Test Rules

Every core model should have at least five regression cases:

- Positive cases
- Boundary cases
- Misuse cases

Regression tests should check whether the model is being used appropriately.

They are not unit tests for code only. They are also product tests for cognitive model stability.

## 9. Selector Rules

The minimal selector should not call an LLM in v0.1.

It should use simple matching rules:

- Trigger keywords
- Input types
- Negative triggers
- Pipeline position
- Selection priority

The selector should output:

- Recommended model IDs
- Scores
- Reasons
- Routing notes

## 10. Coding Style

Keep scripts simple and readable.

Use Python only if scripts are needed.

Avoid unnecessary dependencies.

If using Python, prefer the standard library first.

If a dependency is necessary, document it in README.

## 11. Validation Expectations

Validation should eventually check:

- JSON schema compliance
- Unique model IDs
- Valid source article references
- Valid evidence excerpt references
- Valid regression test model references
- Required fields
- Enum values

Validation output should be written to:

```text
reports/validation_report.md
```

## 12. Documentation Expectations

When adding or changing structure, update relevant documentation.

At minimum, keep these files consistent:

- `README.md`
- `AGENTS.md`
- `docs/PROJECT_BRIEF.md`
- `docs/DATA_CONTRACT.md`
- `docs/WORKFLOW.md`
- `docs/DECISIONS.md`
- `PROJECTS.md`

## 13. Cross-Repository Collaboration Rules

This repository is the product and application boundary for The Mindscape of Bro Tsong.

Use neighboring repositories through explicit request channels:

- `requirements/ccpe/` for expert agents, CCPE-Lite prompt cards, Agent Specs, Committee Specs, Runtime Specs, Model Card governance, Model Index governance, invocation protocols, evaluation rubrics, and integration registrations.
- `requirements/skills-vault/` for reusable automation tools, deterministic scripts, batch processors, validation helpers, extraction utilities, format transformers, and installable automation Skills.

Do not copy canonical CCPE artifacts into this repository.

Do not copy reusable automation Skill source into this repository.

Use installed runnable Skills from:

```text
C:\Users\wangq\.agents\skills
```

If a missing capability blocks model extraction:

1. Classify whether it is a CCPE need or a skills-vault need.
2. Create a request file in the appropriate `requirements/` directory.
3. Pause the dependent extraction step unless the project owner explicitly says to solve it inside this repository.
4. Resume only after the required spec, rule, tool, Skill, or owner decision is available.

Third-party frameworks such as CrewAI or LangGraph belong in this repository only when they implement this product. CCPE may define the agent contract, runtime governance, authority, evaluation, and integration registration. This repository owns application adapters, state, deployment, and product behavior.

## 14. Decision Logging

Any structural decision should be recorded in:

```text
docs/DECISIONS.md
```

Examples:

- Why JSON is used instead of YAML
- Why no database is used in v0.1
- Why QPI and Intellectual Archaeology are the first sample models
- Why selector is rule-based in v0.1
- Why `model_library_mvp` is a phase name rather than a nested repository root
- Why a missing capability was routed to `ccpe-system`, `skills-vault`, or implemented locally

## 15. Definition of Done

A task is done only when:

- Files are created in the expected location
- README or folder README is updated
- JSON files are valid or clearly marked as draft
- References between files are consistent
- Validation status is documented
- Non-goals have not been violated
- Any open questions are listed in the handoff document
- Any missing supplier capability is recorded in `requirements/ccpe/` or `requirements/skills-vault/`

## 16. Handoff Requirement

At the end of a work session, create or update:

```text
docs/HANDOFF_TEMPLATE.md
```

or a concrete handoff file such as:

```text
reports/Codex_工程产物摘要_v0.1.md
```

The handoff should include:

- What was completed
- What files changed
- What assumptions were made
- What does not yet work
- What needs product judgment
- Suggested next tasks