# Requirements Log

This document records product and engineering requirements established during the initial RecoWork design conversations.

## Product Positioning

- RecoWork helps people and the AI agents they already use turn real work into a durable, reviewable working system.
- Its public positioning is: "work standards and project facts for people and AI agents." It fixes the task, professional standards, current project facts, acceptance method, and continuation mechanism; it does not replace an agent runtime.
- It is not a prompt collection.
- It is not another agent platform and does not host models, API keys, background execution, automatic memory, or unattended completion.
- It should help users build durable working systems: prompts, rules, canonical workspace records, memory, quality checks, and usage steps.
- It should serve both technical users and non-technical users across industries.
- It should be usable across different AI products, including web apps, mobile apps, coding agents, and workspace tools.
- The project should remain open-source friendly.
- Public documentation may say RecoWork works with an AI agent the user already uses, but must not present a specific agent product as officially supported unless that compatibility has been actually verified.

## Product Modes

- Local executable agents are the core environment for complete, durable engineered workflows. They initialize directories, rules, indexes, workspaces, intermediate artifacts, knowledge capture, status checks, and safe upgrades.
- Chat and mobile targets are low-friction, immediate conversation workflow entry points. They provide a start instruction, task execution protocol, and continuation or migration summary only.
- Chat and mobile targets must not require or imply Node.js installation, CLI use, local file creation, local workspaces, automatic artifact persistence, file-level traceability, status checks, or upgrades.
- Chat continuity is user-managed: the user saves and pastes a continuation summary into the next conversation.
- Every chat target must offer a migration exit containing a project brief, current decisions, open questions, and next step for initialization in a command-capable local agent.

## Core Concepts

- A reusable work scenario should be represented as a template.
- A target should represent one of two delivery environments: `chat-mobile` or `local-agent-project`.
- A locale should represent the generated language and user-facing naming convention.
- Reusable template methodology should live in `工作方法/`, not `core/` or `method/`.
- Project workspace outputs should use the locale-specific name such as `工作空间/` or `workspace/`.
- Templates and targets must evolve independently.
- Localized template content should live under `templates/<template>/locales/<locale>/` when a template supports multiple languages.
- Localized target content should live under `targets/<target>/locales/<locale>/files/`. Shared target files are reserved for convention-driven or locale-neutral output.
- Localized examples that contain user-facing language should live under the corresponding locale directory and be copied with that locale.
- Avoid duplicating platform-specific output inside every template.
- The CLI should compose a template, target, and locale into files.
- Prompt usage should be a lightweight entry point that asks AI to run the CLI first.

## Initial Templates

The first templates are:

- `idea-to-project`: one staged workflow that starts with exploration and validation, requires explicit direction and project-entry confirmation, then advances through requirements, design, planning, decisions, and review.
- `learning-engineering`: structured learning workflow with learner diagnosis, a roadmap, lessons, practice, projects, feedback, and durable learning records.
- `web-design-standard`: reusable default design guidance for AI-generated or improved HTML and web pages, covering visual consistency, responsive behavior, component states, and accessibility self-review.

Template content quality is intentionally deferred. The architecture should support better, more differentiated templates later.

### Web Design Standard Template

`web-design-standard` validates a single reusable product-web design standard before any generic composition or pack mechanism is introduced.

- Its default direction is restrained, modern, and trustworthy for SaaS, tool products, solo or small-team product sites, and lightweight operations dashboards.
- It is not the default for expressive brand sites, games, complex commerce, or projects with strict existing brand systems. Existing user brand, design-system, and explicit visual requirements always take precedence.
- It must cover scope and use, goals and prohibitions, color/type/spacing/container/radius/border/shadow tokens, desktop and mobile strategy, hierarchy, navigation/buttons/forms/cards/lists-tables/empty-feedback states, AI implementation instructions, and a post-implementation checklist.
- For `local-agent-project`, it produces exactly one localized design-standard document in addition to target-owned `AGENTS.md` and `rw-manifest.json`: `网页设计规范.md` for `zh`, `web-design-standard.md` for `en`. It must not create a design-system directory, workspace, methods, or multiple standard documents.
- For `chat-mobile`, it produces the standard three chat materials only. The start instruction must stand alone and include role, input fields, default direction, tokens, responsive and component rules, prohibitions, output expectations, self-checking, brand priority, and a continuation-summary format. It covers desktop and mobile webpages; it does not request local files or tools.
- This first version must not add template composition, a `packs` CLI option, user-selectable visual styles, image generation, model APIs, or background execution.
- The documentation site keeps one public interactive reference implementation at `docs/demos/web-design-standard/index.html`. It demonstrates the default product-web direction, responsive behavior, and real UI states as a manual acceptance baseline; it is previewed inside a website modal and is not emitted by either target or included in generated user projects.

## Targets and Platform Usage

- RecoWork has exactly two primary targets: `chat-mobile` and `local-agent-project`.
- `local-agent-project` must safely integrate with a root `AGENTS.md`: create the complete file when absent, or preserve an external file while adding a marker-bounded RecoWork block when present. The block contains the template-specific reading, confirmation, review, and durable-context rules, and states that external project rules take priority.
- The manifest must track an externally integrated AGENTS block independently from complete target files. An upgrade may update only an unchanged block; modified or removed blocks are preserved and reported.
- `local-agent-project` is tool-neutral: it generates `AGENTS.md`, methods, workspace records, and a manifest, but no platform-specific skills or configuration folders.
- `chat-mobile` generates only copyable conversation material and never local project configuration.
- Existing brand target names remain CLI aliases only; they do not imply brand-specific output.

## CLI Requirements

- npm package name: `recowork`.
- Executable command: `rw`.
- User-facing brand name: `RecoWork`.
- User-facing abbreviation: `RW`.
- Preferred command should be short and practical:

```bash
rw add <template> --target <target> <destination>
```

- Language-specific output should use:

```bash
rw add <template> --target <target> --locale <locale> <destination>
```

- `rw init` can remain as a compatibility alias if needed.
- CLI initialization should be deterministic file copy/render, not AI-generated long-form reconstruction.
- `rw add` must refuse a destination containing `rw-manifest.json`; users must use `rw status` or `rw upgrade` for an existing initialized workflow.
- CLI should list templates and targets, and `rw show <template>` should show supported locales.
- CLI should support aliases only when they are unambiguous.
- If a requested locale is not supported by the template, the CLI should fail with supported locales.
- New `local-agent-project` initializations must write a versioned `rw-manifest.json` with generated-file hashes and ownership metadata. Chat initializations must not create a manifest.
- `rw status <destination>` and `rw upgrade --check <destination>` must be read-only and explain available template/target updates, user modifications, missing files, and workspace items needing review. When `--scope` is provided, their output must be filtered to that scope.
- `rw upgrade --apply <destination>` may update only unchanged working-method or target files within the selected scope. It must preserve user-modified files.
- Generated workspaces are user-owned. Upgrade must never overwrite, move, delete, restore, or add reports within an existing/tracked workspace file tree. It may add a newly introduced missing workspace file only with both `--scope workspace` and `--add-missing`; upgrade reports live under `.recowork/upgrade-reports/`.
- Legacy manifests without a generated-file baseline must require explicit `rw upgrade --adopt <destination>`; adoption records state without changing project files.
- Legacy chat manifests must never be upgraded in place. `rw status` and `rw upgrade` should provide a read-only migration guide that preserves the old directory and initializes `local-agent-project` in a separate destination.
- `rw view [directory]` must provide a zero-configuration, read-only local Markdown viewer for local workspaces. It starts an HTTP server bound only to `127.0.0.1`, must not write configuration or alter workspace files, should derive normal navigation from `index.md`, and should keep localized archives out of the default current-work view behind an explicit user toggle. It must recognize either an initialized project root or a workspace directory passed directly. Its sidebar navigation must allow each nested branch to be collapsed, with deeper branches collapsed by default. The viewer header and sidebar must remain fixed within the viewport while only the document content scrolls.
- The viewer must localize its own visible UI from the detected workspace locale, including title, navigation, search, archive controls, overview, and empty/error states. Local-agent generated instructions and initialization prompts must tell a command-capable agent to start `npx --yes recowork@latest view .` from the project root after initialization and on a user request to browse or review the workspace. The agent reports the local URL and must not ask the user to install RecoWork, find the workspace directory, or type the command.
- Viewer document routes must be represented in the URL so refresh, browser navigation, and copying the local URL reopen the same document. Search must scan the selected current or archive scope and return a matching document with a concise snippet, including a localized no-results state. The dashboard must keep summaries scannable and show available status or update metadata. Document pages must expose breadcrumb and previous/next navigation based on the workspace navigation order.
- While `rw view` is running, Markdown and index changes in its resolved workspace must refresh the open document and navigation automatically. The viewer remains read-only and may use only local loopback change notifications.
- Viewer Markdown must use a maintained GitHub-flavored Markdown parser with raw HTML disabled. It must support tables, task lists, nested lists, block quotes, code blocks, and images without custom regular-expression rendering; relative image assets must resolve through a restricted, read-only local asset endpoint.
- An unavailable Markdown renderer must not prevent the viewer from loading workspace navigation and its current-work dashboard. Opening a document in that condition must show a localized recovery message instead of a blank page.
- Before creating a local service, `rw view` must probe the local viewer port range and reuse an existing viewer that is already serving the same canonical workspace path. A different workspace or an explicitly requested occupied port must not be reused. Viewer document and image endpoints must not follow workspace symlinks.

## Prompt Requirements

- Prompt mode exists for users who do not want to manually learn the CLI.
- Prompt mode should not embed full template content.
- Local-agent prompt mode should tell AI to run:

```bash
npx --yes recowork@latest add <template> --target <target> <destination>
```

- When language matters, prompt mode should tell AI to run:

```bash
npx --yes recowork@latest add <template> --target <target> --locale <locale> <destination>
```

- Public first-run instructions should use `npx --yes recowork@latest` so the package is fetched without requiring a global `rw` command or an interactive npm installation prompt.
- `rw` may be shown only as an alias for users who have already installed RecoWork globally or inside CLI output after the package is running.

- If a local agent cannot run `npx`, the prompt may instruct it to read the GitHub repository and manually compose `templates/<template>/` with `targets/<target>/`.
- If the template has localized content, fallback prompt mode should instruct AI to use `templates/<template>/locales/<locale>/`.
- Chinese prompt templates should be written in Chinese.
- Website-generated and primary first-run prompts should not include the GitHub repository URL because the npm package is the normal initialization source.
- Reusable fallback prompts may include the GitHub repository URL only as an explicitly conditional source when `npx` cannot run; they must not imply that cloning or reading the repository is part of normal initialization.
- Initialization must distinguish a command-capable local agent from a pure chat/mobile environment.
- A command-capable agent should check Node.js and npm first. If either is missing, unavailable, or outdated, it must ask for confirmation before installing the latest stable Node.js, then run the CLI.
- A pure chat/mobile environment must not be asked to install Node.js or create local files. It should receive a direct, copyable chat bootstrap prompt with the selected workflow's role, working protocol, self-review, and continuation-memory rules.

## Documentation and Website Requirements

- README defaults to English.
- Chinese README filename: `README.zh.md`.
- Website defaults to Chinese.
- Website supports English and Chinese.
- Website is served from `docs/` for GitHub Pages.
- Website should explain the project from a user's point of view, not from internal implementation details.
- Website style should be modern, colorful, and vivid.
- Website should present AI-assisted initialization and CLI initialization as two selectable paths within one initialization area.
- Website should let users select a workflow template, usage target, output locale, and runtime capability, then generate matching copyable CLI and prompt examples.
- Website should avoid overlong or unclear main titles.
- The website must explain value before internal terms such as CLI, template, target, or locale. Its homepage should lead with the user problem: an existing agent needs a concrete, repeatable job to finish.
- Website terminology should use user-facing labels: "work scenario", "usage environment", and "language" rather than template, target, and locale where implementation details are unnecessary.
- The homepage must distinguish local executable agents from Chat / Mobile: local mode is the complete durable workflow; Chat / Mobile is a low-friction conversation entry point with a copyable start instruction, task protocol, and manually saved continuation or migration summary.
- Public copy must state that Chat / Mobile neither creates nor automatically persists a local project workspace, and should guide users to move complex, collaborative, knowledge-heavy, or auditable work to a local executable agent.
- The homepage must present idea-to-project, learning engineering, and web design standard as current choices. It must present the two stages of idea-to-project as one user journey, not competing workflow choices.
- The web-design standard must be shown separately as an independently validated professional standard, rather than misrepresented as another durable project-workflow scenario.

## Packaging and Publishing Requirements

- npm package should include only source assets needed to run RecoWork:
  - `bin/`
  - `cli/`
  - `templates/`
  - `targets/`
  - `prompts/`
  - README files
  - changelog files
- npm package must not include npm cache, generated tgz files, local test output, or generated project output.
- `.npm-cache/`, `node_modules/`, and `*.tgz` should be ignored.
- Publishing requires npm authentication that supports package publish, including 2FA or a granular access token with publish permission when required by npm.
- Every published version must move completed items from `Unreleased` into a dated version section in both `CHANGELOG.md` and `CHANGELOG.zh.md`.
- Every published version must also have a matching Chinese and English entry on the GitHub Pages release record at `docs/releases.html`.
- Before committing a completed user-facing, template, target, CLI, or website change that remains unreleased, add its concise bilingual summary to `CHANGELOG.md`, `CHANGELOG.zh.md`, and the Unreleased section of `docs/releases.html`; the three sources must stay aligned until publication.

## Project Workflow Requirements

- Durable decisions and requirements should be recorded in repo docs, not left only in chat.
- When discussion establishes a new convention, update `AGENTS.md` and the relevant file under `specs/` in the same change.
- Template changes must keep source templates, CLI compatibility cleanup, README/site usage text, and specs consistent.
- Convention-driven filenames must not be translated. Keep names such as `AGENTS.md`, `README.md`, and `index.md` unchanged.
- Chinese can be used in user-facing folder names and document content when the template is Chinese-oriented.
- English locale output should use English user-facing folders and documents, such as `methods/`, `workspace/`, `project-brief.md`, and `open-questions.md`.
- Chinese locale output should use Chinese user-facing folders and documents, such as `工作方法/`, `工作空间/`, `项目简报.md`, and `待确认问题.md`.
- Locale applies to user-facing target paths and static target text as well as template content. Durable knowledge is consolidated into canonical workspace documents; do not generate a separate `知识库/` or `knowledge/` directory.
- Project-oriented templates should include a role contract that defines the AI role, working principles, core capabilities, prohibited behavior, and iteration rules.
- Role contracts should be localized with the template content. For `idea-to-project`, use `工作方法/角色设定.md` in `zh` and `methods/role-contract.md` in `en`.
- Generated project rules should explicitly tell AI to read the role contract before planning or executing project work.
- AI-generated changes should be reviewed before being presented as complete.
- AI role contracts must require objective judgment: identify material risks, contradictions, weak assumptions, and credible alternatives; disagree respectfully when warranted instead of concealing concerns to satisfy the user.
- Large or ambiguous design changes should be confirmed before broad execution.
- Test output generated in the repository root should be cleaned up.
- Verification commands should be reported after meaningful code changes.
- Every template with a durable workspace must generate localized document conventions: `工作方法/文档规范.md` for `zh` and `methods/document-standard.md` for `en`.
- Every template with a durable workspace must also generate a localized artifact freshness standard: `工作方法/产物保鲜规范.md` for `zh` and `methods/artifact-freshness-standard.md` for `en`.
- Except for `index.md`, substantial workspace documents use metadata, a conclusion-first summary, structured body, relative references, and a change log; each document covers one stable topic or responsibility.
- `index.md` is navigation only: one-line entries, relative links, status, and last-updated state, without copied body content. Formal workspace indexes list only current or still-open material; historical versions are navigated only from a separate localized workspace archive index.
- Formal work is organized by stable topics or modules, not by each discussion or agent action. Each module directory has an `index.md` as its current entry point and a localized authority document named `整体方案.md` (`zh`) or `overall-plan.md` (`en`). Create a responsibility-specific child document only when it has an independent lifecycle, audience, review path, or change cadence; otherwise update the authority document in place. Child filenames describe both their object and responsibility when the directory context is insufficient, and never use iteration labels such as “final”, “latest”, or version suffixes.
- Agents start from the relevant root index, retrieve focused documents progressively, and update affected indexes after material work.
- Artifact freshness uses `草稿` / `评审中` / `当前有效` / `已替代` / `已归档` (`Draft` / `In review` / `Current` / `Superseded` / `Archived`). A topic and scope has one current default source. Superseded formal versions and completed process traces are stored only in `归档/<分类>/<主题>/v<主版本>.<次版本>.md` or `archive/<category>/<topic>/v<major>.<minor>.md`; active directories keep only current or still-open material. Before moving, archiving, deleting, renaming, or rewriting an existing user-owned document, agents must present the candidate, reason, destination, and replacement and obtain confirmation.
- Commits must follow Conventional Commits using `<type>(<scope>): <summary>`; the full contributor guidance lives in `CONTRIBUTING.md`.
- Commits that span multiple surfaces, introduce migrations, alter generated output, or are otherwise non-obvious require `Why`, `Changes`, `Compatibility`, and `Validation` sections in the body.
- Incompatible command, generated-path, file-format, or workflow-contract changes require a `BREAKING CHANGE:` footer.
- Template and target manifests must declare semantic versions. A meaningful generated-content change increments its owning template or target version and is described in the release record.
- Retired templates must not appear in new initialization, list, show, prompt, README, or website selection surfaces. Existing generated files remain user-owned; `rw status` and `rw upgrade` provide read-only migration guidance instead of an in-place conversion.

## Idea To Project Workspace Requirements

The `idea-to-project` template should generate one concise Chinese-oriented `工作空间/` structure:

```text
工作空间/
├── index.md
├── 项目简报.md
├── 待确认问题.md
├── 搁置想法.md
├── 01-探索与验证/
├── 02-需求与约束/
├── 03-方案设计/
├── 04-计划与决策/
├── 05-过程留痕/
├── 06-评审验证/
└── 归档/
```

The Chinese locale should also generate:

```text
工作方法/
└── 角色设定.md
```

The Chinese locale must also generate `工作方法/文档规范.md`; the English locale must generate `methods/document-standard.md`. This working method defines a five-part document structure (metadata, conclusion first, body, relative references, and change log), modular authority documents, index-only navigation rules, progressive retrieval, and index-status maintenance after work.

Responsibilities:

- The workflow has a mandatory stage gate: explore and validate first, then present a direction decision package and wait for explicit confirmation before project entry. After project entry, confirm material scope before a complete solution, plan, or implementation. An explicitly confirmed local task may proceed without repeated confirmation.
- `项目简报.md`: project background, problem, goals, scope, non-goals, current status, and constraints.
- `待确认问题.md`: questions that AI must not silently assume.
- `搁置想法.md`: ideas or directions that are not being advanced now but may restart; every entry records its reason, restart condition, priority, last assessment, related material, and next step. It is a current workspace document, not an archive or a list of blocking open questions.
- `01-探索与验证/`: problem, candidate directions, hypotheses, evidence, validation, and a direction decision package.
- `02-需求与约束/`: requirements, user scenarios, constraints, assumptions, and clarifications after project entry.
- `03-方案设计/`: tradeoff analysis, feasibility, architecture, technical design, and implementation path.
- `04-计划与决策/`: phases, milestones, execution plan, and durable decisions.
- `05-过程留痕/`: active project process traces and discussion summaries that are not yet absorbed or closed.
- `06-评审验证/`: review notes, validation results, acceptance checks, and follow-up items.
- `归档/`: the dedicated entry point for superseded formal versions and completed process material, organized by category, topic, and version.

The old seven-part split must not be generated by default:

- `00-项目总览/`
- `01-需求分析/`
- `02-分析评估/`
- `03-技术设计/`
- `04-项目规划/`
- `05-决策记录/`
- `06-思考留痕/`
- `07-评审验证/`

`index.md` filenames remain unchanged because they are navigation conventions. User-facing folder names and content can be Chinese.

The English locale should generate the same structure in English-oriented names:

```text
workspace/
├── index.md
├── project-brief.md
├── open-questions.md
├── parked-ideas.md
├── 01-exploration-and-validation/
├── 02-requirements-and-constraints/
├── 03-solution-design/
├── 04-plan-and-decisions/
├── 05-thinking-traces/
├── 06-review-and-validation/
└── archive/
```

The English locale should also generate:

```text
methods/
└── role-contract.md
```

## Learning Engineering Workspace Requirements

The `learning-engineering` template should turn learning into a validated progression of diagnosis, units, practice, projects, retrospectives, and reusable knowledge. It should not generate a complete course as one long answer.

The Chinese locale should generate:

```text
工作方法/
├── 角色设定.md
├── 学习方法.md
├── 课程单元模板.md
└── 评估与复盘.md

学习空间/
├── index.md
├── 学习简报.md
├── 课程路线.md
├── 学习进度.md
├── 01-课程设计/
├── 02-课程与练习/
├── 03-项目实践/
├── 04-问题与复盘/
├── 05-知识沉淀/
└── 归档/
```

The English locale should generate the equivalent structure under `methods/` and `learning-workspace/`:

```text
learning-workspace/
├── index.md
├── learner-brief.md
├── course-roadmap.md
├── learning-progress.md
├── 01-course-design/
├── 02-lessons-and-practice/
├── 03-project-practice/
├── 04-questions-and-retrospectives/
├── 05-knowledge-capture/
└── archive/
```

Responsibilities:

- The role contract defines a curriculum designer, subject mentor, and practice coach role.
- Learning initialization has a mandatory confirmation gate: diagnose the learner, present a concise learning agreement, and wait for explicit confirmation before generating or changing a roadmap, lesson content, practice plan, or project plan. An explicitly confirmed local unit may proceed without repeated confirmation.
- The learner brief captures the learner's foundation, target ability, constraints, preferences, and completion criteria.
- The roadmap records unit dependencies, practice output, acceptance criteria, and a throughline project.
- Each learning unit should include a goal, a minimal experiment, practice, feedback, verification, and learner-owned explanation.
- Code or operational courses should show the problem, key change, actual verification, and data-flow reasoning; they must not claim unrun work succeeded.
- The workspace separates course design, lessons, project work, questions/retrospectives, and validated knowledge capture. Current learning records stay in those formal areas; superseded versions and completed process material enter the localized archive only after learner confirmation.

## Legacy Idea Engineering Compatibility

`idea-engineering` and `project-engineering` are retired in favor of `idea-to-project`. Existing generated workspaces remain user-owned and are never converted in place. `rw status` and `rw upgrade` provide a read-only guide to initialize `idea-to-project` in a separate destination and transfer only the current brief, confirmed decisions, open questions, and next step. The historical layout below is retained only to describe legacy user output; it must not be emitted by new initialization.

The Chinese locale should generate:

```text
工作方法/
├── 角色设定.md
├── 文档规范.md
├── 发散与收敛方法.md
├── 假设与验证规范.md
└── 产物保鲜规范.md

想法空间/
├── index.md
├── 想法简报.md
├── 待确认问题.md
├── 01-问题与机会/
├── 02-脑暴留痕/
├── 03-方向归纳/
├── 04-假设与验证/
└── 05-决策与下一步/
```

The English locale should generate the equivalent structure under `methods/` and `idea-space/`, including `methods/document-standard.md` and `idea-space/05-decisions-and-next-steps/`.

Responsibilities:

- The role contract defines a rigorous idea exploration facilitator, strategy advisor, and validation coach.
- Idea initialization has a mandatory confirmation gate: clarify the exploration frame and diverge first; wait for explicit user confirmation before selecting a priority direction, creating a validation plan, or entering project execution.
- The idea brief is the current agreement for the exploration; open questions contain items AI must not silently assume.
- Problem/opportunity, brainstorming traces, direction synthesis, hypotheses/validation, and decisions/next steps keep process material separate from current conclusions.
- Confirmed directions, validation conclusions, and next steps must be captured in `05-决策与下一步/` or `05-decisions-and-next-steps/`; no separate `知识库/` or `knowledge/` directory is required for this template.

## Naming Requirements

- Use `RecoWork` in user-facing text.
- Use `RW` for the abbreviation.
- npm package remains lowercase `recowork`.
- CLI binary remains lowercase `rw`.