docs(readme): 强化 Codex 导向的项目呈现

Author: sincerely90

AGENTS.md

@@ -1,10 +1,30 @@
-# AGENTS.md
+# Agent Instructions for Aisee Plugin
+
+## 项目目的
+
+Aisee Plugin 是一个面向 Codex 的 OpenSpec 工作流层，用于支持 spec-driven AI software engineering。
+
+## 工程原则
 
 - 默认使用中文回复和编写文档，除非用户明确要求其他语言。
 - 保持 Aisee、OpenSpec、Compound Engineering 的职责边界清晰。
+- 保持 CLI 公共命令行为稳定；除非用户明确要求，否则不要引入破坏性变更。
+- 优先做小而可审查的改动；行为变化要同步更新测试和用户可见文档。
+- 不要移除 OpenSpec、Codex、schema pack、context pack、verification 或 archive 相关能力，除非有明确替代方案。
+- 修改 skill 时保持 `SKILL.md` 精简，将长规则放入 `references/` 或 `docs/architecture/`。
+- 不要把教程站内容放入本仓库。
+
+## 事实源边界
+
 - OpenSpec change 和 baseline 是规范事实源；不要创建平行规范事实源。
 - Aisee CLI 的 JSON 输出应调用时解析 Markdown、OpenSpec artifacts、`source-map.md`、`tasks.md`、evidence 和少量 planning doc metadata。
 - 不要把编号、索引或缓存升级成独立规范事实源；context pack 的内部扫描视图只服务本次输出。
 - `tasks.md` 是唯一长期任务清单；`ce-plan` 只能作为按需细化器，结论必须回写 `tasks.md` 或 `source-map.md`。
-- 修改 skill 时保持 `SKILL.md` 精简，将长规则放入 `references/` 或 `docs/architecture/`。
-- 不要把教程站内容放入本仓库。
+
+## Review 指引
+
+- 将 CLI 行为损坏、schema 处理失效、不安全文件写入和误导性文档视为高优先级问题。
+- 检查生成路径是否安全，避免覆盖当前项目之外的文件或无关目录。
+- 检查 JSON / YAML 输出是否仍保持机器可读、字段稳定且示例可复现。
+- 检查 README、示例和命令说明是否与当前实现一致。
+- 检查示例是否能从干净仓库 checkout 后复现，尤其是 OpenSpec、Codex 和 archive 相关流程。

README.en.md

@@ -29,18 +29,39 @@
 
 # Aisee Plugin
 
+> Aisee Plugin is a Codex-oriented OpenSpec workflow layer for spec-driven AI software engineering.
+
 **Aisee** stands for **AI-Enhanced Software Engineering**.
 
 Aisee Plugin is an AI software engineering plugin for OpenSpec workflows. It helps teams turn ambiguous ideas into reviewable requirements, UI content specifications, architecture context, OpenSpec changes, project memory, team knowledge guardrails, implementation briefs, verification checks, and archive guardrails.
 
 Aisee **does not replace OpenSpec**. OpenSpec remains the specification state machine and baseline source of truth. Aisee adds structured skills, project memory, team knowledge, JSON context tooling, and engineering handoff rules around OpenSpec.
 
+It is especially relevant for maintainers who want Codex and other coding agents to work more reliably in open-source repositories:
+
+- durable requirements and specifications instead of transient chat context;
+- machine-readable context packs and schema packs for implementation, review, and verification;
+- OpenSpec change planning that turns vague intent into reviewable deliverables;
+- implementation briefs that help maintainers and contributors hand off PR-ready work;
+- verification evidence and archive gates that close the loop before AI-assisted changes are treated as complete.
+
 ## OpenSpec Boundary
 
 Aisee does not replace OpenSpec and does not maintain a second schema state machine. Aisee reads the current schema declaration only when handling OpenSpec changes, context packs, or schema pack checks; project memory and team knowledge remain guidance / guardrails.
 
 When Aisee handles OpenSpec artifacts, it acts only as a parser / checker / projector. `openspec validate` and `openspec archive` remain OpenSpec responsibilities.
 
+## Why This Matters for Codex
+
+Codex can write, review, and fix code, but the results are less reliable when a repository lacks explicit requirements, stable project context, review rules, and verification criteria.
+
+Aisee supplies that workflow layer:
+
+- it turns intent into durable OpenSpec changes, planning docs, and reusable project memory;
+- it helps maintainers prepare implementation briefs that are easier to review and hand off;
+- it lets Codex read against the same context boundaries across implementation, review, verification, and archive;
+- it gives open-source projects clearer engineering constraints for AI-assisted contribution flows.
+
 ## Why Aisee?
 
 AI coding assistants are useful, but projects drift when requirements, UI decisions, technical constraints, and implementation evidence live only in chat history.
@@ -578,6 +599,9 @@ python scripts/smoke_release.py --with-pipx
 
 ### Later
 
+- Add stronger Codex PR review and implementation-brief examples for maintainer workflows.
+- Add a sample OpenSpec change so new repositories can see a concrete Aisee deliverable.
+- Expand verify/archive gate examples to lower the trial cost for OSS maintainers.
 - Improve project memory conflict hints, stale-entry policy, and low-context injection rules.
 - Tighten team knowledge remote sync, promote workflows, lifecycle management, and optional MCP wrapping.
 

README.md

@@ -29,18 +29,39 @@
 
 # Aisee Plugin
 
+> Aisee Plugin is a Codex-oriented OpenSpec workflow layer for spec-driven AI software engineering.
+
 **Aisee** 是 **AI-Enhanced Software Engineering** 的缩写。
 
 Aisee Plugin 是一个面向 OpenSpec 工作流的 AI 软件工程插件。它帮助团队把模糊想法整理成可审查的需求、UI 内容规格、技术架构上下文、OpenSpec changes、项目记忆、团队知识 guardrails、实现交接 brief、验证检查和归档门禁。
 
 Aisee **不替代 OpenSpec**。OpenSpec 仍然是规范状态机和 baseline 事实源。Aisee 在 OpenSpec 周围补充结构化 skills、project memory、team knowledge、JSON context tooling 和工程交接规则。
 
+它尤其适合希望让 Codex 和其他 coding agent 在开源仓库中更稳定协作的维护者：
+
+- 用可持久复用的需求与规范，替代只存在于聊天记录里的临时上下文；
+- 用机器可读的 context pack 和 schema pack，为实现、审查和验证提供稳定输入；
+- 用 OpenSpec change planning 把模糊意图拆成可审查、可交付的变更；
+- 用 implementation brief 帮助 maintainer 和 contributor 做 PR / review-ready 交接；
+- 用 verification evidence 和 archive gates 收口 AI 辅助开发后的验收与归档流程。
+
 ## OpenSpec Boundary
 
 Aisee 不替代 OpenSpec，也不维护第二套 schema 状态机。只有在处理 OpenSpec change、context pack 或 schema pack 检查时，Aisee 才读取当前 schema 声明；project memory 和 team knowledge 始终只是 guidance / guardrails。
 
 当 Aisee 处理 OpenSpec artifacts 时，它只做 parser / checker / projector；`openspec validate` / `openspec archive` 仍由 OpenSpec 负责。
 
+## 为什么这对 Codex 很重要？
+
+Codex 能写代码、审代码、修 bug，但在仓库没有显式需求、稳定上下文、审查规则和验证标准时，结果容易依赖短期 prompt 历史。
+
+Aisee 把这些材料前置为可复用的工作流层：
+
+- 让需求和工程约束以 OpenSpec change、planning docs 和 project memory 的形式持久存在；
+- 帮助维护者把实现意图整理成更容易 review 的 implementation brief；
+- 让 Codex 在实现、review、verify 和 archive 之间读取同一套上下文边界；
+- 为开源仓库提供更明确的 AI 协作约束，降低 maintainer 反复补充背景的成本。
+
 ## 为什么需要 Aisee？
 
 AI coding assistant 很有用，但当需求、UI 说明、技术约束和实现证据长期停留在聊天记录里时，项目很容易上下文漂移。
@@ -577,6 +598,9 @@ python scripts/smoke_release.py --with-pipx
 
 ### 后续
 
+- 补充更贴近 maintainer 场景的 Codex PR review / implementation brief 示例。
+- 增加 sample OpenSpec change，帮助新仓库快速理解 Aisee 的交付形态。
+- 扩展示例化的 verify / archive gate 文档，降低 OSS 维护者的试用门槛。
 - 完善 project memory 的冲突提示、过期策略和低上下文注入规则。
 - 收敛 team knowledge 的远程同步、promote workflow、生命周期管理和可选 MCP 包装。