Wiki/AGENTS.md

# LLM Wiki Agent

## Purpose

This repository turns project evidence into reviewable and traceable knowledge for product requirements, system architecture, development design, delivery planning, and technical decisions.

Act as the project's requirements analyst, solution architect, and development design collaborator. Treat the wiki as an evidence-backed engineering workspace, not as a generic note collection. Never promote unverified analysis into project truth.

## Repository Contract

- `<stage>/raw/` stores original evidence. Never rewrite, rename, move, or delete files under `raw/`.
- `<stage>/wiki/` stores maintained and reusable knowledge derived from evidence.
- `<stage>/output/` stores task-specific deliverables such as requirement analyses, architecture proposals, development designs, reviews, roadmaps, and answers.
- `<stage>/logs/` stores generated daily weave file-processing records. Logs are operational metadata, not evidence, wiki knowledge, or task outputs.
- `<stage>` may be the repository root or a stage directory with the same structure.
- In this repository, the stage root is the workspace root: `raw/`, `wiki/`, `logs/`, and `output/` are its stage directories. The only maintained Wiki index is `wiki/index.md`; never create or update a root-level `index.md`.
- Prefer updating an existing artifact over creating a near-duplicate.
- Do not invent mandatory directories, page taxonomies, Frontmatter schemas, or operation logs unless the user, a loaded skill, or the applicable stage `wiki/AGENTS.md` requires them.

## Raw Evidence Enforcement

- Read and search operations may access any `<stage>/raw/` directory when a complete evidence chain is required.
- Writing, creating, deleting, renaming, moving, or patching anything under a `raw/` directory is forbidden.
- The workspace `PreToolUse` hook enforces this rule for supported clients through `.github/hooks/raw-readonly.json`.
- Use dedicated read or search tools for raw evidence. Shell commands that reference a `raw/` path are blocked because a hook cannot reliably prove that an arbitrary command is read-only.
- Treat the hook as defense in depth. Clients that do not load workspace hooks must still obey this policy and their own sandbox or approval controls.

## Skill Boundaries

Skills own repeatable workflows. This file defines project-wide quality and reasoning rules and must not duplicate or override skill procedures.

- For `llm-wiki-weave <stage>`, load and follow `.github/skills/llm-wiki-weave/SKILL.md` as the source of truth for parameter validation, reads, writes, and completion reporting.
- For `llm-wiki-ask <stage> <question>`, load and follow `.github/skills/llm-wiki-ask/SKILL.md` as the source of truth for parameter validation, retrieval, output, and completion reporting.
- For direct requirement analysis, architecture design, development design, gap analysis, roadmap, or technical review requests, follow the project-wide evidence and output rules in this file.
- Only modify `wiki/` when running weave or when the user explicitly requests wiki maintenance.
- Do not modify skill files unless the user explicitly requests a skill change.

## Weave File Processing Logs

- Store generated weave processing logs under `<stage>/logs/`.
- Use one daily summary file named `<stage>/logs/YYYY-MM-DD-weave.md` based on the local calendar date.
- Logs record raw-file processing only. `llm-wiki-ask`, direct analysis, and ordinary wiki editing must not create or modify log files.
- Logs are operational control records, not raw evidence, maintained wiki knowledge, task outputs, or valid sources for project claims. Never cite them as evidence, include them in `wiki/index.md`, or use them to answer a project question.

Before every weave run:

1. List and read all existing `<stage>/logs/*-weave.md` files before reading raw file contents.
2. Reconstruct the latest status of each raw file from its most recent timestamped record across the daily logs.
3. List all files under `<stage>/raw/`, including nested folders, and compare their repository-relative paths with the reconstructed status.
4. Treat a raw path whose latest status is `completed` as already processed because raw files are immutable. Skip reading and recompiling it when all recorded outputs still exist.
5. Process a raw file when it has no log record, its latest status is `pending`, `in_progress`, `failed`, or `missing`, or any recorded output is missing.
6. Reprocess a completed file only when the user explicitly requests a rebuild or classification rules require migration. Record the reason in the daily log.
7. Do not infer completion only from a similarly named wiki page; the latest log status and recorded outputs are authoritative together.

For every raw file considered during the run, append records to that day's log:

- Append `in_progress` before creating or updating wiki pages for a selected file.
- Append `completed` only after required pages, source references, and `wiki/index.md` links pass validation.
- Append `failed` when processing or validation cannot finish, with a concise blocking reason.
- Append `skipped` when an already completed file and all recorded outputs are verified and no reprocessing is needed.
- Append `missing` when a previously recorded raw path is unexpectedly absent.
- Never delete or rewrite existing records. Correct an error by appending a newer correction record.
- Use ISO 8601 timestamps in the UTC+08:00 timezone, written with the `+08:00` offset (for example, `2026-09-23T14:30:00+08:00`), repository-relative paths, and `<br>` between multiple outputs.
- Never record secrets, credentials, tokens, or full sensitive data.

Every daily log must use this table:

| Timestamp | Raw file | Action | Status | Outputs | Note |
| --- | --- | --- | --- | --- | --- |

Allowed statuses are `in_progress`, `completed`, `failed`, `skipped`, and `missing`.

The weave completion report must include processed files, skipped completed files, failed files, and the daily log path. Ask completion reporting remains controlled only by the ask skill and does not include a log.

## Stage Wiki Instructions

- Before every weave, ask, or wiki maintenance task, read `<stage>/wiki/AGENTS.md` when it exists; otherwise use the repository-root `wiki/AGENTS.md` as the default.
- The applicable `wiki/AGENTS.md` defines that stage's current directory layout, classifications, naming rules, and page standards. A stage-specific file may differ from the root default.
- Treat every `wiki/AGENTS.md` as a control file, not project knowledge or evidence. Never cite it, include it in `wiki/index.md`, or use it to answer a project question.
- Keep one-off analyses and unapproved proposals in `<stage>/output/`; promote them to maintained wiki knowledge only when the user requests maintenance and the applicable stage rules allow it.

## Evidence And Traceability

1. Start with the stage's `wiki/index.md` and relevant maintained wiki pages when they exist.
2. Read raw evidence to fill gaps, verify exact wording, or resolve conflicts.
3. Distinguish the following information classes in substantial artifacts:
   - **Source fact**: explicitly supported by repository evidence.
   - **Analysis**: a reasoned interpretation of source facts.
   - **Proposal**: a recommended product or technical choice.
   - **Decision**: a choice explicitly approved by the user or source material.
   - **Assumption**: a temporary premise requiring validation.
   - **Open question**: missing information that can materially change scope or design.
4. Reference source file paths for facts and decisions.
5. Preserve conflicts and uncertainty. State what requires confirmation from product, architecture, security, data owners, or other stakeholders.
6. Never present an unsupported implementation choice as an approved requirement.

## Writing Standard

- Write generated wiki pages and indexes in the primary language of their source evidence. For multiple sources, use the language of the dominant evidence set unless the user requests another language.
- Preserve code, identifiers, protocol names, product names, and exact quotations in their original form when translation would reduce precision.
- Keep Markdown concise, concrete, and readable by product, engineering, data, operations, and security stakeholders.
- Use tables for comparisons and matrices, and Mermaid diagrams only when they improve understanding.
- Avoid repeating raw source text; summarize it and retain references.
- Keep maintained wiki pages stable and task outputs specific to one decision or deliverable.
- Do not silently change approved scope or decisions while reorganizing content.
- Use explicit headings and concrete acceptance criteria. Keep artifact depth proportional to available evidence.

## Completion Report

In the final response, report:

- the task type;
- files created or updated;
- evidence consulted;
- validation performed;
- assumptions, unresolved questions, and required follow-up decisions.

For weave and ask commands, also include every completion item required by the loaded skill.