docs(agents): 优化 Astra 自主执行、授权与完成规则 - #39
Conversation
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
@codex review |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e2bc3139ab
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| [workflow-state:planning] | ||
| Load `trellis-brainstorm`; stay in planning. | ||
| Lightweight: `prd.md` can be enough. Complex: finish `prd.md`, `design.md`, and `implement.md`; ask for review before `task.py start`. | ||
| Multi-deliverable scope: consider a parent task plus independently verifiable child tasks; dependencies must be written in child artifacts, not implied by tree position. | ||
| Sub-agent mode: curate `implement.jsonl` and `check.jsonl` as spec/research manifests before start. | ||
| Inspect evidence; use trellis-brainstorm only for material ambiguity. Record concise scope/acceptance in prd.md; add design/implementation documents only when useful. If independently delegating, supply relevant context. When implementation is authorized and no material blocker remains, run task.py start and continue without another approval. Planning-only requests end with the plan. |
There was a problem hiding this comment.
When Claude starts, clears, or compacts a session with a task in planning, .claude/hooks/session-start.py:388-410 still injects the old requirements that complex tasks add design.md/implement.md, ask for review, and not begin implementation until the user confirms. That runtime prompt directly conflicts with this new no-second-approval rule, so the repeated pauses this commit is intended to remove remain on every such session transition; update the hook's planning branch along with the workflow text.
AGENTS.md reference: AGENTS.md:L53-L53
Useful? React with 👍 / 👎.
| #### 1.0 Create/reuse task `[when needed · once]` | ||
|
|
||
| **Format**: one JSON object per line — `{"file": "<path>", "reason": "<why>"}`. Paths are repo-root relative. | ||
| Check `task.py current --source` and `task.py list`. Reuse a matching task; create one for product work or useful durable coordination without asking process consent. Simple answers, read-only audits, and narrow documentation/rule maintenance need no task. Honor an explicit request to skip Trellis with a proportionate inline plan. |
There was a problem hiding this comment.
For product work started while the repository is on main, this paragraph tells the agent to create the task before the following paragraph checks the branch. task.py create immediately writes task.json, prd.md, and context manifests, so following the documented order modifies files on main; move the branch/status check ahead of any task creation.
AGENTS.md reference: AGENTS.md:L61-L62
Useful? React with 👍 / 👎.
| Load `trellis-before-dev` when coding, read relevant context, and implement the requested outcome directly. Preserve unrelated changes and scope. Prefer existing APIs/patterns; add abstractions only for demonstrated complexity or meaningful duplication. | ||
|
|
||
| #### 2.2 Quality check `[required · repeatable]` | ||
| Delegate only a concrete independent task that improves time/quality when active instructions permit it. Platform support does not require delegation. Include `Active task: <task path>` when present, role, owned files, inputs, output, and completion criteria. Dispatched agents execute their roles without recursively spawning the same implement/check role. If an agent type is unavailable, work inline. |
There was a problem hiding this comment.
When an agent uses the Trellis customization references, .claude/skills/trellis-meta/references/local-architecture/workflow.md:23-28 still says sub-agent-capable platforms dispatch implement/check agents by default, while customize-local/change-workflow.md:20,42-44 directs maintainers to a removed Skill Routing table and platform groups. Those references can reintroduce mandatory delegation or send maintainers to nonexistent edit points, so synchronize them with this new usefulness-based routing structure.
AGENTS.md reference: AGENTS.md:L56-L56
Useful? React with 👍 / 👎.
| ### Workspace System | ||
|
|
||
| Records every AI session for cross-session tracking under `.trellis/workspace/<developer>/`. | ||
| `create` seeds `task.json` and `prd.md`, with optional context manifests; `--slug` omits the date prefix. `start` sets `in_progress` and the session pointer. If session identity is missing, follow the command's hint using the real current session identifier. `finish` clears the pointer without completing the task. `archive` sets `completed`, moves the task, clears matching pointers, and can auto-commit. Inspect `--help` and configuration before commands with commit/external effects. |
There was a problem hiding this comment.
For anyone creating a task with --slug, this says the option removes the date prefix, but .trellis/scripts/common/task_store.py:240-244 always constructs the directory as MM-DD-<slug>; the updated brainstorm skill also correctly documents that behavior. Correct this sentence so agents do not derive or report the wrong task path.
Useful? React with 👍 / 👎.
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a29d719d55
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ### Useful Content | ||
|
|
||
| For triggered tasks, include all sections below: | ||
| Include only the applicable details below, preferably in existing sections. Do not add empty sections, duplicate code/tests, or require a seven-section rewrite for a small contract change: |
There was a problem hiding this comment.
When trellis-update-spec handles a small contract change for which only one of the listed details applies, this instruction now says to omit the other sections, but the final Quality Checklist at lines 323–328 still requires a code example, signatures, an error matrix, Good/Base/Bad cases, and tests. An agent following the whole skill will therefore either fail its completion gate or recreate the seven-section documentation bloat this change is intended to remove; qualify those checklist items as applicable-only as well.
AGENTS.md reference: AGENTS.md:L56-L56
Useful? React with 👍 / 👎.
| **Find and explain the evidence needed by the research brief.** | ||
|
|
||
| Conversations get compacted; files don't. Every research output MUST end up as a file under `{TASK_DIR}/research/`. Returning findings only through the chat reply is a failure — the caller cannot read them next session. | ||
| Return concise findings with source locations. Persist expensive-to-recover evidence or an explicitly requested research artifact under the caller's task research directory. A brief read-only lookup can return directly; file count does not establish research quality. |
There was a problem hiding this comment.
For a taskless or brief read-only lookup, the new contract permits returning findings directly without creating an artifact, but .claude/skills/trellis-meta/references/platform-files/agents.md:15 still defines this agent as writing into the current task's research/, and customize-local/change-agents.md:44 still says research always persists. Because trellis-meta is the guidance used when maintaining these agent definitions, following it can reintroduce mandatory persistence or leave the agent requiring a nonexistent task directory; update those references to match this conditional contract.
AGENTS.md reference: AGENTS.md:L56-L56
Useful? React with 👍 / 👎.
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4511206e1e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| Inspect relevant code, current instructions, and decisions. Define the outcome, boundaries, and acceptance evidence in a concise PRD or inline plan. Use `trellis-brainstorm` for consequential ambiguity; choose routine implementation details yourself. Ask the smallest useful set of questions and continue independent work. | ||
|
|
||
| These manifests do not replace `implement.md`. `implement.md` is the human-readable execution plan for a complex task; jsonl files only list context files to inject or load. | ||
| Add design/implementation documents only when their separate purpose justifies them. Do not split tasks or rewrite a sufficient PRD merely for a formatting gate. Update the plan when evidence changes scope/acceptance. |
There was a problem hiding this comment.
Whenever task.py create is used, .trellis/scripts/common/task_store.py:186-188 writes the old requirement into the generated prd.md, and lines 353-356 repeat it in the command's immediate “Next steps” output. Agents creating any complex product task therefore still receive two task-specific instructions to add design.md and implement.md before task.py start, directly defeating this new usefulness-based rule; update the task template and CLI output as part of the policy change.
AGENTS.md reference: AGENTS.md:L56-L56
Useful? React with 👍 / 👎.
|
@codex review |
|
Codex Review: Didn't find any major issues. Bravo. Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
1 participant
用户已要求实现的工作会被 Trellis 的建任务、开始实现、设计检查点和提交确认反复暂停；固定文档、讨论轮次与验证要求也会扩大小任务，并导致收尾依赖用户再次操作。
统一 AGENTS.md、Trellis 工作流、实际 SessionStart/状态提示、Skills、继续/收尾命令和子 Agent 定义：在已有目标和授权内持续执行，只澄清实质缺口；按风险选择规划、委派和验证；区分本地交付、提交、PR、合并、发布和归档。创建任务文件前先检查分支，保留 main 分支保护约定、PR 合入、最新提交 Codex review 和禁止直接写业务数据库等约束。
验证：
git diff --check通过。task.py create，确认生成的 PRD、命令提示、日期 slug 和可选文档策略；实际 check/finish 子 Agent 提示构建检查通过。本次涉及 23 个仓库内指令、Hook 和任务生成文件，不修改业务实现或部署服务。个人目录的全局配置与安装技能不属于本仓库，未包含在此 PR。Trellis 升级仍需保留这些本地工作流策略。