sync(workflows): document task.py rename and the empty jsonl manifests

[sdelmas]

Replaces #17, which I have closed — it was written before mindfold-ai/Trellis#573 and its diff no longer applies cleanly on top of the current mirror.

Four hunks, mirroring the Trellis-side follow-up to mindfold-ai/Trellis#578 (companion: sdelmas/Trellis upstream-pr/workflow-doc-sync):

• task.py rename <name> <new-slug> [--dry-run] added to the task lifecycle command block. The command shipped in #578 with no entry here.
• step 1.3 no longer claims the manifests arrive holding a self-describing _example line — task create writes them empty.
• the "delete the seed line once real entries exist (optional — it's skipped automatically by consumers)" note is replaced by the shipped rule: a legacy _example row is rejected by task.py validate and by PR preflight, so it is not optional.
• the ready gate names the empty manifest rather than the seed row, and points at start --allow-empty-context.

What this PR deliberately does not do

workflows/native/workflow.md on this branch is not byte-identical to packages/cli/src/templates/trellis/workflow.md on Trellis main, and I did not try to make it so.

The two have diverged in both directions:

• this mirror carries the DSH class-2 sub-agent blocks from feat(workflow): add native DSH synchronization #13 and docs(workflow): clarify DSH foreground dispatch #14. Their Trellis counterparts (feat(dsh): add native subagent workflow on beta Trellis#548, #550) merged into feat/v0.7-beta, not main, so Trellis main still lists DeepSeek Harness as an inline platform.
• Trellis main has since gained the task_error breadcrumb (#544) and the seed-only context gate (#573), neither of which is here.

Converging this file to Trellis main would revert the DSH work. That is a call for you and @SajoLuo, not something to fold into a docs sync, so this PR touches only the four hunks and leaves both divergences alone.

The consequence: the byte-identity assertion in trellis.test.ts still cannot be satisfied by pinning Trellis at this branch. It is satisfied by an off-main mirror commit, the way sync/native-workflow-seed-gate does it today — see the companion PR for the exact tree.

🤖 Generated with Claude Code

https://claude.ai/code/session_018GfcLh1HJThrTKsURgP8Ja

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: 8e6679c1-1a43-4d23-89f8-d2d44120a67a

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

Updates the native workflow documentation to match recent Trellis task lifecycle behavior around task renaming and JSONL context-manifest creation/validation, ensuring the workflow guidance reflects the current “empty manifest” and legacy _example rejection rules.

Changes:

• Documented task.py rename <name> <new-slug> [--dry-run] in the task lifecycle command list.
• Updated step 1.3 to state implement.jsonl / check.jsonl are created empty on task create (not seeded with _example).
• Clarified that legacy _example rows are rejected by validation/preflight and that empty/legacy-only manifests are not “ready” without start --allow-empty-context.

Suppressed comments (2)

workflows/native/workflow.md:55

• The comment describing implement.jsonl / check.jsonl as "seeded" on task create contradicts the updated guidance below that these files are created empty. This can mislead readers about whether an _example row is expected to exist.

This issue also appears on line 425 of the same file.

python3 ./.trellis/scripts/task.py rename <name> <new-slug> [--dry-run]   # rename task and every reference to it
python3 ./.trellis/scripts/task.py list [--mine] [--status <s>]
python3 ./.trellis/scripts/task.py list-archive

# Code-spec context (injected into implement/check agents via JSONL).

workflows/native/workflow.md:427

• The new text states task.py validate / PR preflight reject legacy _example rows and that empty manifests are not planning-ready, but step 1.4 still says runtime consumers tolerate "seed-only" manifests. That sentence is now internally inconsistent with the stricter validation described in this section.

Tasks created by older Trellis versions may still carry a legacy `{"_example": ...}` placeholder row. Delete it — `task.py validate` and PR preflight both reject it.

Ready gate: both `implement.jsonl` and `check.jsonl` must contain at least one real `{"file": "...", "reason": "..."}` entry before `task.py start`. An empty manifest is not ready, and neither is one holding only a legacy `_example` row. Pass `start --allow-empty-context` when running without spec context is intentional.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[sdelmas]

One handoff note, since the Trellis-side companion cannot open green without you.

The Trellis change (the same four hunks in .trellis/workflow.md and packages/cli/src/templates/trellis/workflow.md) has to move the marketplace gitlink with it, or trellis.test.ts > marketplace native workflow mirror goes red. As explained in the description, this branch is not a candidate for that pin — it keeps the DSH blocks, so it is not byte-identical to the Trellis main template.

So the pin needs an off-main mirror commit, exactly like sync/native-workflow-seed-gate today. I have built it and verified it, but it lives on my fork, and the submodule URL points here, so I cannot make it resolvable:

• sdelmas/marketplace branch sync/native-workflow-doc-sync, commit eaf3dbc22152d94efb670dcb275ebda253a46a47
• parent is 21c7fc2c, the commit Trellis main pins today
• diff against that parent is the same 4 insertions / 3 deletions as this PR
• workflows/native/workflow.md there is byte-identical to packages/cli/src/templates/trellis/workflow.md after the Trellis-side edit — verified with diff, and the mirror assertion passes locally (vitest run test/templates/trellis.test.ts: 26 passed; full CLI suite 82 files / 1896 passed)

If you push that tree to a branch here, I will bump the gitlink to your commit and open the Trellis PR green. Happy to do it the other way round if you would rather land the Trellis docs first and repoint afterwards — just say which.

Separately, and not part of this PR: .trellis/tasks/08-05-session-identity-propagation/{implement,check}.jsonl on Trellis main still carry the legacy _example row, so they now fail task.py validate and PR preflight. The #578 migration stripped 16 manifests; that task appears to have been added after. Worth a one-line cleanup by whoever owns it.

🤖 Generated with Claude Code

[SajoLuo]

Thanks for the precise handoff. I verified the proposed mirror commit locally:

• eaf3dbc22152d94efb670dcb275ebda253a46a47 has parent 21c7fc2c59e7544405bfbb2e2f307e5bee6e6ce5
• its only diff is workflows/native/workflow.md (4 insertions, 3 deletions)
• I agree with keeping the DSH blocks in this PR and using the off-main mirror commit for the Trellis main gitlink
• both 08-05-session-identity-propagation/{implement,check}.jsonl files on current Trellis main still contain the legacy _example row

The blocker is repository permission: SajoLuo currently has READ, not WRITE, on mindfold-ai/marketplace, so I cannot publish sync/native-workflow-doc-sync here myself.

@taosu0216, could you please push Sven's already-verified eaf3dbc tree to mindfold-ai/marketplace:sync/native-workflow-doc-sync? Once that commit is reachable from the submodule remote, Sven can bump the gitlink and open the Trellis companion green.

I can handle the two legacy manifest rows as a separate narrow Trellis cleanup so it stays out of this PR.

[sdelmas]

Closing this: the branch has diverged from main since it was opened three weeks ago, and I am no longer tracking the change on my side. Happy to reopen a fresh pull request against current main if the task.py rename and the empty jsonl manifests are still worth documenting.