# Architecture Decisions

## 001. Use Templates Instead of Packages

Decision: RecoWork work scenarios are called templates.

Reason:

- "Package" sounded like a complete bundled product for every platform.
- Templates better express reusable workflow structure.
- Template content can improve independently from platform output rules.

## 002. Separate Templates From Platform Output

Decision: Do not store complete platform output inside every template.

Reason:

- Per-template adapters duplicate too much content.
- Adding a new platform would require editing every template.
- A shared target layer lets all templates reuse the same platform output rules.

## 003. Replace Platform With Target

Decision: RecoWork should use targets for user-facing initialization.

Reason:

- Platform brand names are ambiguous.
- Claude chat and Claude Code project have different file conventions.
- ChatGPT web/mobile, Codex projects, Cursor projects, Notion workspaces, and Feishu docs are different output environments.

Implication:

- `--target` should become the preferred CLI option.
- `--platform` may remain as a compatibility alias only for unambiguous mappings.

## 004. Prompt Mode Should Invoke the CLI

Decision: Prompt mode should ask AI to run the RecoWork CLI first.

Reason:

- Asking AI to reconstruct files from long context is slow.
- It burns tokens and increases hallucination risk.
- CLI-based initialization is deterministic and faster.

Fallback:

- If commands are unavailable, AI may manually compose `templates/<template>/` and `targets/<target>/` from the GitHub repository.

## 005. Claude Chat and Claude Code Are Different Targets

Decision: Split Claude usage into at least `claude-chat` and `claude-code-project`.

Reason:

- Claude chat needs copyable instructions and prompts.
- Claude Code projects need real project files and project-scoped skills.
- Project-scoped Claude Code skills belong under `.claude/skills/<skill-name>/SKILL.md`.
- Project instructions belong in `CLAUDE.md`.

## 006. Specs Live Under specs

Decision: Product and engineering specs live in `specs/`.

Reason:

- `docs/` is already the GitHub Pages source and should stay focused on the website.
- Specs should be visible in the repository and easy to link from README or the site.
- Keeping specs separate from website UI files avoids mixing product policy with presentation code.

## 007. English README, Chinese Website Default

Decision: The repository README defaults to English, while the GitHub Pages website defaults to Chinese. Both surfaces provide Chinese and English content.

Reason:

- An English README keeps the repository approachable for a broad open-source audience.
- The website is currently oriented toward the project's primary Chinese-speaking users and should be immediately usable without a language switch.

Implication:

- `README.md` remains English and `README.zh.md` remains its Chinese counterpart.
- `docs/index.html` starts with `zh-CN`, the Chinese toggle active, and Chinese metadata.
- The language toggle must update visible text, page metadata, and copyable command examples.
## 008. Keep Project Engineering Workspace Concise

Decision: The `project-engineering` template should use a concise `工作空间/` structure with five main sections:

- `01-需求与约束/`
- `02-方案设计/`
- `03-计划与决策/`
- `04-过程留痕/`
- `05-评审验证/`

Root workspace documents:

- `项目简报.md`
- `待确认问题.md`
- `index.md`

Reason:

- A separate `00-项目总览/` duplicates `项目简报.md`.
- Splitting analysis and technical design too early makes the template feel heavy for new projects.
- Splitting project planning and decisions creates too many folders before the user has enough content.
- Five sections preserve the engineering workflow while keeping the generated structure easier to understand.

Implication:

- The CLI should clean up known old workspace files and empty old directories when re-initializing `project-engineering`.
- User-facing Chinese template content should avoid leftover English scaffold terms such as `Purpose`, `Documents`, and `TBD`.
- Future template structure changes must update the source template, CLI cleanup rules, and specs together.
- The project mentor must present a concise project agreement and wait for explicit confirmation before generating a complete solution, plan, or implementation change; explicitly confirmed local tasks may proceed without repeated confirmation.

## 009. Add Locale as a First-Class Initialization Option

Decision: RecoWork initialization should support locale selection:

```text
template + target + locale = initialized workflow
```

CLI:

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

Reason:

- Users may want the same workflow in different languages.
- Language changes affect user-facing folder names and document names, not only text content.
- Duplicating whole templates for every language would make template maintenance harder.

Implication:

- Localized template content should live under `templates/<template>/locales/<locale>/`.
- `pack.yaml` can declare `default_locale` and `locales`.
- Targets remain language-neutral unless a platform convention itself is language-specific.
- Convention-driven filenames remain unchanged across locales.

## 010. Add Role Contract to Project-Oriented Templates

Decision: `project-engineering` should include a localized role contract:

- `zh`: `工作方法/角色设定.md`
- `en`: `methods/role-contract.md`

Reason:

- A project workflow needs a durable AI role definition, not only task prompts.
- The role should constrain judgment, confirmation behavior, scope control, and quality standards.
- The role should evolve as users add project-specific preferences and working rules.

Implication:

- Generated project rules should instruct AI to read the role contract before project work.
- The role contract should be maintained like other working methods when user feedback changes expected behavior.
- Avoid vague role claims; specify responsibilities, principles, prohibited behavior, and iteration rules.

## 011. Engineer General AI Workflows Around Tasks, Not Projects

Superseded by Decision 024. This entry records the original rationale for the retired template.

Decision: `general-ai-workflow` uses the same durable principles as `project-engineering` but a lighter task-oriented structure.

- `zh`: `工作方法/` and `工作空间/`
- `en`: `methods/` and `workspace/`
- The workspace separates task setup, output, thinking traces, and review/reuse.
- Both locales include a role contract, workflow, quality checklist, and continuation memory template.

Reason:

- Everyday chat and mobile AI users need continuity and quality controls without adopting a full project-management workspace.
- A task brief and open-question list make AI clarification behavior visible and reusable.
- Separating final output from traces prevents chats from becoming one unstructured, hard-to-resume record.

Implication:

- `general-ai-workflow` supports `zh` and `en`, with localized names and examples.
- CLI re-initialization cleans up known legacy general-workflow files and empty directories.
- Chat prompts must render in the selected locale and refer users to the role contract.

## 012. Engineer Learning Around Validated Units And Throughline Practice

Decision: `learning-engineering` should use a localized role contract and a dedicated learning workspace, informed by the LangChain TypeScript learning project.

- `zh`: `工作方法/` and `学习空间/`
- `en`: `methods/` and `learning-workspace/`
- Root learning documents are learner brief, roadmap, and progress.
- Learning work is separated into course design, lessons/practice, project practice, questions/retrospectives, and knowledge capture.

Reason:

- A study plan alone does not demonstrate mastery; each unit needs practice, verification, and a learner-owned explanation.
- A throughline project gives otherwise isolated concepts a concrete application and an evolving acceptance surface.
- Recording actual commands, results, errors, and reasoning makes technical learning reproducible rather than performative.

Implication:

- The learning mentor must diagnose before teaching, present a concise learning agreement, and wait for explicit confirmation before generating course design; it then teaches one validated unit at a time.
- Templates must support code and non-code learning without assuming a specific file extension or technology stack.
- The CLI cleans up known legacy learning-template files on re-initialization.

## 013. Choose Initialization By Runtime Capability

Decision: RecoWork initialization should distinguish runtime capability from the output target.

- A command-capable local agent, including Codex, Cursor, and Claude Code, can initialize any target through an AI-guided CLI flow.
- That flow checks Node.js and npm first; if either is missing, unavailable, or outdated, it asks the user before installing the latest stable Node.js.
- A pure chat or mobile environment receives a direct chat bootstrap prompt and is restricted to chat targets. It must not be instructed to install Node.js or create local project files.

Reason:

- Codex, Cursor, and Claude Code can converse and run commands, so a chat-led initialization flow can still produce deterministic project files.
- Mobile chat products do not have a shell or writable project directory; treating them as failed CLI environments produces unusable instructions.

Implication:

- Target describes the desired output surface; runtime capability describes how initialization can happen.
- Website initialization controls must collect both values and change available paths accordingly.
- Prompt templates for local agents must include runtime checks and confirmation before installing Node.js.

## 014. Treat Document Conventions As A First-Class Working Method

Decision: every RecoWork template with a durable workspace includes a localized document standard separate from workflow steps and quality gates.

- `zh`: `工作方法/文档规范.md`
- `en`: `methods/document-standard.md`

Reason:

- Workflow describes when work happens; quality gates check whether work is ready; neither defines how durable project knowledge is structured, linked, retrieved, and maintained.
- A fixed document shape makes conclusions discoverable and lets AI retrieve only the context needed for the current task.

Implication:

- Non-index documents use metadata, conclusion-first summary, structured body, relative references, and a change log.
- `index.md` files remain lightweight navigation only, with one-line entries, relative links, status, and last-updated state.
- Agents navigate from indexes, retrieve focused documents progressively, and update affected indexes after material work.
- Every durable template also has a localized artifact freshness standard. It separates canonical facts from traces, defines current and historical lifecycle states, and requires a consolidation sweep at meaningful completion points without automatically deleting user documents.

## 015. Localize Target Outputs, Not Only Templates

Decision: targets support locale-specific output files under `targets/<target>/locales/<locale>/files/`.

Reason:

- Templates already localize their working methods and workspaces, but target-level paths and static content are also user-visible.
- Leaving targets language-neutral caused Chinese initialization to generate English paths such as `knowledge/` and English prompt or document filenames.
- Tool conventions and user-facing content need different treatment.

Implication:

- The CLI renders shared target files first, then selected localized target files.
- Localized target files may translate user-facing paths, filenames, and static content.
- Shared target files are reserved for convention-driven or locale-neutral output.
- Keep `AGENTS.md`, `CLAUDE.md`, `SKILL.md`, `.claude/`, and `rw-manifest.json` unchanged.
- When an existing RecoWork target is re-initialized in another locale, remove previous locale-specific generated files that do not exist in the selected locale.

## 020. Separate Lightweight Chat Entry From Durable Local Workflows

Decision: Chat and mobile targets remain supported, but they are lightweight conversation workflow entry points rather than equivalent versions of local engineered workflows. Local executable agents are the core environment for full RecoWork capability.

Reason:

- Pure chat and mobile environments do not provide a reliable local filesystem, command runtime, artifact lifecycle, or upgrade surface.
- Pretending that a chat conversation owns a workspace creates false expectations about persistence and traceability.
- Chat remains valuable as an immediate, low-friction way to clarify work, execute a focused task, self-review output, and prepare a clean handoff to a local agent.

Implication:

- Chat targets provide only a copyable start instruction, task execution protocol, and continuation or migration summary.
- Chat targets do not create template workspaces or `rw-manifest.json`, and they do not support status checks or upgrades.
- Continuity is manual: users save and paste the summary into the next chat.
- When work becomes complex, long-running, collaborative, knowledge-heavy, or auditable, the chat flow produces a migration package with project brief, current decisions, open questions, and next step for Codex, Claude Code, Cursor, or another local executable agent.

## 016. Use Conventional Commits With Structured Large-Change Bodies

Decision: RecoWork uses Conventional Commits and requires structured commit bodies for broad or compatibility-relevant changes.

Reason:

- Commit history is part of the durable engineering record and must be useful to people and AI agents.
- A short title alone cannot explain a change that crosses templates, targets, CLI behavior, generated output, and specifications.
- Explicit compatibility and validation notes make upgrades and regressions easier to assess.

Implication:

- Commit titles use `<type>(<scope>): <summary>`.
- Broad changes include `Why`, `Changes`, `Compatibility`, and `Validation` in the commit body.
- Incompatible changes include a `BREAKING CHANGE:` footer.
- `CONTRIBUTING.md` is the detailed contributor-facing source; `AGENTS.md` applies the same standard to AI agents.

## 017. Treat The Changelog As A Release Artifact

Decision: every RecoWork release updates bilingual changelog sources and the bilingual website release record before publication.

Reason:

- npm versions alone do not explain behavioral changes, migration needs, or known compatibility limits.
- Repository readers and website visitors need the same release facts in their preferred language.
- Keeping release notes as a required artifact prevents version history from becoming dependent on chat or commit archaeology.

Implication:

- `CHANGELOG.md` is the English release source and `CHANGELOG.zh.md` is its Chinese counterpart.
- `docs/releases.html` presents the same release history in Chinese and English.
- A release must move entries out of `Unreleased`, state compatibility or migration notes, and update all three surfaces before `npm publish`.

## 018. Upgrade Generated Assets Without Taking Ownership Of User Workspaces

Decision: RecoWork uses a versioned generated-file manifest and a conservative upgrade advisor.

- New initializations write `rw-manifest.json` schema version 2 with RecoWork, template, and target versions plus source and baseline hashes for generated files.
- `rw status` and `rw upgrade --check` are read-only. `rw upgrade --plan` shows the same per-file recommendations in detail.
- `rw upgrade --apply` may update only an unchanged working-method or target file. If a user changed a file, it remains untouched and is reported.
- Workspaces are user-owned. RecoWork never automatically overwrites, moves, deletes, or recreates an existing/tracked workspace document.
- `rw upgrade --apply --scope workspace --add-missing` may create only a newly introduced workspace template that is absent. When the workspace scope is explicitly selected, it writes a localized upgrade report under `.recowork/upgrade-reports/` for the user or AI to review.
- Older manifests require `rw upgrade --adopt` to record the present state without modifying project files.

Reason:

- Working methods and tool conventions benefit from controlled updates, while project briefs, decisions, traces, and learning records are the user's durable assets.
- Re-initialization cannot distinguish template evolution from intentional project work, and therefore is unsafe as an upgrade mechanism.
- Hash baselines make the upgrade decision explicit instead of relying on timestamps or best-effort text merges.

Implication:

- Templates and targets declare a semantic `version` in their manifests and increment it when their generated contract changes.
- New template workspace files are surfaced as recommendations, not silently inserted into a working project.
- Workspace migrations require user confirmation and should use the generated report as a scoped task brief for a human or AI assistant.

## 019. Separate Idea Exploration From Daily Tasks And Project Execution

Superseded by Decision 024. This entry records the original relationship between idea exploration and daily task work.

Decision: `idea-engineering` is a dedicated workflow for AI-assisted brainstorming, direction synthesis, and hypothesis validation. `general-ai-workflow` is presented to users as the daily task workflow while retaining its stable internal ID for compatibility.

Reason:

- Daily task collaboration should stay lightweight and may complete clear tasks directly.
- Idea exploration needs deliberate divergence, evidence-aware convergence, and a confirmation point before committing to a direction.
- Project engineering begins after a direction has enough agreement to justify solution design and execution planning.

Implication:

- `idea-engineering` uses localized `想法空间/` and `idea-space/` workspaces with problem, trace, synthesis, validation, and next-step sections.
- The template supports chat, project, workspace, and document targets and waits for explicit confirmation before a priority direction, validation plan, or project execution.
- Confirmed directions can be handed to `project-engineering` with the idea agreement and evidence preserved.

## 020. Collapse Brand Targets Into Two Environment Contracts

Decision: RecoWork exposes only `local-agent-project` and `chat-mobile` as primary targets. Brand-specific targets, native skills, and document-platform exports are removed.

Reason:

- Brand-specific target files duplicated the same workflow contract, increased maintenance cost, and made target selection harder than necessary.
- `AGENTS.md` is the common instruction surface across the supported local-agent workflow.
- A separate knowledge folder duplicates the canonical project, learning, task, or idea records already owned by the workspace.
- RecoWork cannot reliably provide document synchronization or collaboration; users should synchronize their actual workspace through the tools they choose.

Implication:

- `local-agent-project` generates tool-neutral `AGENTS.md`, methods, workspace records, and a manifest. It does not generate `.claude/`, `.cursor/`, `CLAUDE.md`, or skills.
- `chat-mobile` is a lightweight conversation entry point and produces only a start instruction, task protocol, and manual continuation/migration summary.
- Durable conclusions are consolidated into canonical workspace documents and their indexes, never into a separate `knowledge/` or `知识库/` directory.
- Legacy brand target names remain CLI aliases for compatibility, but no longer select brand-specific output. Existing user workspaces are preserved untouched.
- Decisions 003 and 005 are superseded where they prescribe brand-specific targets or Claude-native skills.

## 021. Validate Web Design Guidance As A Standalone Template

Decision: introduce `web-design-standard` as a standalone template before adding generic work-pack composition.

Reason:

- Web design guidance is likely to be reused across projects, but real reuse must be validated before introducing template composition, `packs` CLI options, or user-selectable style systems.
- A single product-web default is enough to validate whether users value reusable visual tokens, responsive rules, component-state requirements, and self-checking.
- A durable project workspace would add noise for a reusable design standard whose job is to constrain page work, not manage a project.

Implication:

- The local target produces target-owned `AGENTS.md`, `rw-manifest.json`, and exactly one localized standard: `网页设计规范.md` or `web-design-standard.md`.
- The Chat target remains a lightweight three-document delivery. Its start instruction is a complete standalone prompt that covers both desktop and mobile web work and never requests local files or tools.
- Existing brand guidance and explicit user visual requirements override the default standard.
- Do not add composition, a `packs` CLI option, multiple style choices, image generation, model APIs, or background execution in this iteration.

## 022. Safely Integrate With Existing Root AGENTS.md

Decision: `local-agent-project` automatically integrates RecoWork instructions into an existing root `AGENTS.md` through a marker-bounded block, rather than requiring manual copy or overwriting the file.

Reason:

- A template that is initialized but never referenced by the project's instruction entry point is unlikely to take effect.
- Existing root instructions are user-owned and may contain important project conventions that RecoWork cannot replace safely.
- A stable block boundary makes the RecoWork portion independently traceable and upgradeable.

Implication:

- When root `AGENTS.md` is absent, RecoWork creates the complete target-owned file. When present, it preserves existing content and appends or updates `<!-- recowork:start ... -->` through `<!-- recowork:end -->` only.
- The block states that external project rules have priority and contains the selected template's localized protocol.
- The manifest records the managed block's marker and hashes separately. Upgrades may replace only an unchanged block; user-edited or removed blocks are preserved and reported.
- The behavior applies only to the initialization root. Nested instruction files are not discovered or modified.

## 023. Maintain Unreleased Changes With Each Completed Commit

Decision: completed unreleased user-facing changes are recorded before their commit in the bilingual Markdown changelogs and the bilingual Unreleased section of the website release page.

Reason:

- Deferring changelog work until publication causes committed capabilities to be invisible to repository and website readers.
- A continuously maintained Unreleased section makes the next release scope reviewable without reconstructing history from commits.
- Keeping all three public records aligned avoids different audiences receiving different expectations of unreleased behavior.

Implication:

- User-facing template, target, CLI, or website changes add a concise Unreleased entry as part of completion, before commit.
- `CHANGELOG.md`, `CHANGELOG.zh.md`, and `docs/releases.html` describe the same pending changes in their respective languages.
- Release preparation moves the already-recorded entries into a dated version section; it does not recreate release notes from commit history.

## 024. Retire The Daily Task Workflow Template

Decision: retire `general-ai-workflow` and its `general`, `task`, and `daily` aliases. RecoWork no longer offers a generic daily-task workflow as a new initialization choice.

Reason:

- Its scope overlaps ordinary chat usage but does not offer a sufficiently distinct, repeatable workflow to justify a dedicated template.
- The remaining templates have clearer intent: idea exploration, project engineering, structured learning, and web design standards.
- Keeping a weakly differentiated template makes selection harder and dilutes product guidance.

Implication:

- Remove its source template, CLI list/show/add access, prompts, README entries, site cards, configuration options, cases, and workspace requirements.
- Existing generated `general-ai-workflow` files are user-owned and remain untouched.
- `rw status` and `rw upgrade` detect a legacy general manifest and print a read-only migration guide to a separate idea or project workflow; they never perform an in-place conversion.
- Decisions 011 and 019 are superseded only where they prescribe `general-ai-workflow` as an active template.

## 026. Unify Idea Exploration And Project Advancement

Decision: replace the user-visible `idea-engineering` and `project-engineering` choices with the staged `idea-to-project` template.

Reason:

- Users experienced the two previous templates as overlapping choices because both clarify, record facts, and require confirmation.
- The actual user journey is continuous: explore an uncertain direction, validate it, explicitly choose whether to commit, then advance the confirmed project.
- A single workspace creates a traceable handoff without asking users to choose or migrate between two similar templates.

Implication:

- Stage one is `Exploration And Validation`: problem, directions, assumptions, evidence, validation, and a direction decision package.
- The user must explicitly choose to continue exploration, validate a key assumption, or enter a project. Only explicit project entry unlocks full requirements, solution, planning, implementation, review, and acceptance work.
- Stage two is `Project Advancement`: the confirmed direction package becomes input to the project brief and numbered project sections.
- `chat-mobile` remains three lightweight materials only, with stage judgment, a confirmation gate, and a manual continuation/migration summary; it creates no local files.
- `idea-engineering` and `project-engineering` are retired. Existing workspaces are user-owned and receive only a read-only separate-destination migration guide from status or upgrade.

## 025. Keep A Public Reference Implementation For The Web Design Standard

Decision: retain one interactive website example for `web-design-standard` at `docs/demos/web-design-standard/index.html` and expose it inside a large preview modal from the design-standard card and configuration flow.

Reason:

- Tokens and written rules alone do not let users quickly judge the intended default product-web direction.
- A functioning example verifies that the standard can produce responsive layout, meaningful component states, and accessible interaction instead of a static screenshot.
- The example gives maintainers a stable manual acceptance baseline when the standard evolves.

Implication:

- The example is documentation-site content, not a generated template asset and not a new output from either target.
- It uses the default restrained product-web direction and covers navigation, primary action, filtering, loading, empty state, form validation, and success feedback.
- Future changes to the web-design standard should check the example against the same responsive, state, and accessibility criteria.

## 027. Separate Current Work From Historical Archives

Decision: durable workspaces expose only current or still-open material in their formal directories and normal indexes. Superseded formal versions and completed process material are retained only in a localized workspace archive, organized as category, topic, and version.

Reason:

- Co-locating historical versions with canonical documents makes both people and agents select stale context, causing duplicate edits and ambiguous project facts.
- Preserving history remains necessary for decisions, milestones, comparisons, and traceability, but it should be retrieved deliberately rather than loaded as normal working context.

Implication:

- Every durable workspace includes `归档/index.md` (`zh`) or `archive/index.md` (`en`) as the dedicated historical entry point.
- Archive paths use `归档/<分类>/<主题>/v<主版本>.<次版本>.md` or `archive/<category>/<topic>/v<major>.<minor>.md`; do not pre-create empty categories.
- Formal indexes list Current or still-open material only, while archive indexes list the historical category, topic, version, status, and one-line summary.
- Routine changes update the current source in place. Archive snapshots are reserved for milestones, external deliveries, confirmed decisions, material retrospectives, or meaningful comparisons.
- Existing user files remain user-owned: before any move, archive, deletion, rename, or rewrite, agents propose the candidate, reason, destination, and replacement and wait for confirmation.

## 028. Keep Restartable Ideas Separate From Archives And Open Questions

Decision: `idea-to-project` keeps a localized current list for ideas or directions that are intentionally not being advanced now but may restart later.

Reason:

- A direction that is deferred for timing, evidence, or capacity reasons is neither a blocking uncertainty nor obsolete history.
- Leaving it only inside discussion traces or a decision package makes it hard to review, resume, and prioritize without re-reading old context.

Implication:

- Local workspaces generate `搁置想法.md` (`zh`) or `parked-ideas.md` (`en`) as the single scan-friendly list.
- Each entry records the idea, parking reason, restart condition, priority, last assessment, related material, and next step.
- Parked ideas stay out of the active project scope and default execution plan, but remain Current workspace material; they are reviewed at milestones or when the user raises the direction again.
- Chat/mobile does not create files, but its task protocol and continuation summary retain parked directions and restart conditions.
- An item enters the archive only after explicit abandonment, replacement, or a user-confirmed need for historical retention.

## 029. Provide A Read-Only Local Workspace Viewer

Decision: provide `rw view [directory]` as a built-in, zero-configuration local reader for RecoWork Markdown workspaces.

Reason:

- A durable workspace is useful only if people can scan current facts without manually traversing many Markdown files.
- A generated documentation site or a VitePress configuration would introduce generated assets, build maintenance, and another mutation surface into a user-owned project.
- The existing `index.md` and current-versus-archive convention already provide enough structure for a focused first reader.

Implication:

- `rw view` runs a local HTTP service bound to `127.0.0.1` and opens the browser when possible; `--no-open` and `--port` support constrained environments. Its visible UI follows the detected workspace locale.
- The supplied directory may be either an initialized project root or the workspace itself; an `index.md` at the supplied root is treated as the workspace entry point.
- It never writes configuration, generated sites, manifests, or workspace content.
- It follows normal `index.md` links for navigation, shows recognized current brief, open questions, parked ideas, and learning progress as overview entries, and hides `归档/` or `archive/` until the user explicitly opens it.
- It is an optional local-agent companion, not a target, a replacement for the website, or a static-site export feature.
- Local-agent instructions direct the agent, not the user, to start `npx --yes recowork@latest view .` after initialization and on a user request to browse or review the workspace. The command discovers the localized workspace from the project root and requires no global install.
- The viewer uses URL document routes, scope-aware full-text search, short overview summaries with metadata, and breadcrumb plus previous/next navigation to make long workspaces recoverable without directory traversal.
- A maintained browser Markdown parser renders GitHub-flavored Markdown while raw HTML remains disabled. Relative image sources are mapped to a restricted local asset endpoint rather than exposing arbitrary workspace files, and the reader never follows workspace symlinks. The local service uses canonical workspace paths when probing and reusing an existing process.

## 030. Organize Current Work By Stable Modules

Decision: organize durable formal work by stable topics or modules instead of creating a document for each discussion, iteration, or agent action. Every module has an `index.md` as its current entry point and an authority document: `整体方案.md` for Chinese workspaces and `overall-plan.md` for English workspaces.

Reason:

- Indexes alone help readers find documents but do not prevent a directory from accumulating overlapping files.
- A stable module boundary gives both people and agents one default source to update while preserving a clear way to scale complex projects.
- Responsibility-based child documents keep specialized material reviewable without turning every note or revision into a standalone artifact.

Implication:

- The authority document states the module's current overall conclusion, boundaries, key choices, and links to any specialized child documents.
- Create a child document only when it has an independent lifecycle, audience, review path, or change cadence; otherwise update the authority document in place.
- Child filenames use stable, user-understandable object-and-responsibility names when their directory does not provide enough context; never use process, “final”, “latest”, or version names for current documents.
- `index.md` remains navigation only. Process traces are consolidated into the authority or responsibility-specific document once validated, then handled under the existing archive protocol.