Summarize large project workflow in Traces
Public
Summarize large project workflow in Traces
Agent
OpenCode
Model
Kimi-K2.6
StartedMay 25, 2:51 AM
Shared
May 25, 2:52 AM
Messages55
Downloads1
Workspace
Review past projects in code/traces.
UnderstandWrite summary of large project handling in Traces.
PlanShare summary to Traces platform.
SetupPrepare summary for social media posting.
VerifyI want you to go through the past projects in code/traces and write up a summary of how we handle larger projects in Traces
Once you're done, share to traces and I'll post this on social media
The user wants me to:
code/tracesLet me first explore what's in the code/traces directory to understand the context.
>ls -la /Users/tarunsachdeva/code/tracesLet me look at the traces_list to see what past sessions are available. Also, I should explore the traces project structure a bit more.
The user wants me to go through past projects in code/traces and write up a summary of how we handle larger projects in Traces, then share it to traces.
Looking at the traces list and the AGENTS.md, I can see a lot of sessions related to the Traces project. Let me look at some key sessions that seem to be about project management and larger project handling. I'll look at some notable sessions:
But wait, the user is asking about how WE handle larger projects in Traces. Let me think about what I can observe from the session titles and patterns. However, I think I should look at some specific sessions to get actual content about how larger projects are handled. Let me look at a few key sessions that mention worktrees, project plans, and phased implementation.
Actually, looking more carefully, there are sessions about:
Let me fetch some of these sessions to understand the patterns better. I'll need to use some way to get the content. But I don't have a direct tool to fetch trace content. Let me look at the project files themselves to understand the patterns.
Let me look at:
Actually, I can look at the docs/ folder and any project-related files in the repo itself.
Let me look at the docs/projects folder and the AGENTS.md section about managing projects. I should also look at some specific sessions if possible. Let me explore the projects folder and some relevant docs.
Let me look at some specific project docs to understand how larger projects are handled. I'll look at the project-baton.md, some of the larger project plans, and maybe some specific sessions.
The feed-remodel.md doesn't exist in the projects folder. Let me look at a few more project files to understand the patterns. Let me also look at some of the traces sessions that seem to be about project management. Let me fetch some of the notable sessions by looking at what files exist in the traces directory and maybe grep for "worktree" or "project" or "phase" in the traces sessions. But I don't have a direct way to read trace session content.
However, from the AGENTS.md and the project-baton.md, I can already see a lot of patterns. Let me also look at a few more project docs and perhaps some relevant session logs if they are stored locally.
Let me look at more project docs to understand the patterns.
Let me look at more project docs and also maybe find some sessions that have content about project handling. Let me look at a few more project files and also grep for worktree/project patterns.
Now I have a good picture. Let me also look at a couple more project docs and perhaps some specific sessions. Let me also look at the trace session files if they are stored locally. But looking at the available info, I can see clear patterns:
Let me also look at a few more things - maybe the git worktree pattern, and some more docs.
>ls /Users/tarunsachdeva/code/traces-worktrees 2>/dev/null || echo "No worktrees dir"Now I have a good understanding of the patterns. Let me also look at a couple more traces sessions to understand the actual project handling. Let me look for some session data if available, or look at a few more project docs. I think I have enough to write a comprehensive summary. Let me look at one or two more docs and maybe check a trace session file if they exist.
Now I have a very comprehensive picture. Let me also look at a few more items to round out my understanding - specifically the session storage location and some of the "worktree" sessions.
>grep -r "worktree" /Users/tarunsachdeva/code/traces/docs/ 2>/dev/null | head -30Now I have a very comprehensive understanding. Let me compile this into a well-written summary. The key patterns I've observed are:
~/code/traces-worktrees/project-baton, feat-org-namespaces, etc.)docs/projects/ with executive summary, goals/non-goals, key decisions, phases, and verification commandsLet me write a comprehensive summary and then share it to traces.
Now I need to share this to Traces. The user asked me to share it to Traces after I'm done. Let me use the traces_share tool.
The summary is written and shared to Traces. I should present the summary to the user and provide the Traces share URL.
Here's the summary, written up and shared to Traces:
Share URL: https://traces.com/s/jn7cv65nqg078jp61bgs4h1my587dtcr
Over the past few months of building Traces, we've developed a consistent playbook for tackling larger features. It's not formal process for its own sake — it's a set of habits that keep a small team moving fast without breaking things. Here's how it works.
Before code, we write a project doc in docs/projects/. This isn't a vague RFC. It's a working document that lives with the code and gets updated as decisions change.
A typical project doc includes:
Examples: docs/projects/project-baton.md, docs/projects/namespace-improvements.md, docs/projects/share-to-traces-skills.md.
Every significant project gets its own git worktree under ~/code/traces-worktrees/. This means:
main stays clean and deployablemain are never blocked by in-progress workWe have a helper script (scripts/new-worktree.sh) that creates a worktree and sets up the branch. When a project doc references a worktree, it always includes the exact path.
We start at the lowest level and work up:
@traces/shared) — define the contract firstThis rule is encoded in our AGENTS.md:
"MUST: Start at lowest level — API, Types before frontend" "NEVER: Change API, CLI, Frontend all at once unless permitted"
The benefit: each layer validates the one below it. By the time you reach the frontend, the types and API contract are already solid.
Large projects are never one big PR. They're a stack of small, atomic, independently mergeable PRs.
For example, the Namespace Improvements project shipped in 8 stacked PRs:
Each phase:
main after mergeWe use a rebase workflow: after PR N merges to main, rebase PR N+1 onto main, force-push, and retarget the GitHub PR.
We write failing tests before implementation. This is explicit in our project docs:
Phase 1: Tests (RED) — write tests that prove the desired contract
Phase 2+: Implementation (GREEN) — make them pass
Policy tests are the "source of truth" for access control. HTTP endpoint tests are minimal "wiring checks" that verify the policy is correctly hooked up. This means behavioral rules live in one place, and if you change a policy, you update one test file.
Test hygiene is strict:
feed_unauth_returns_public_onlyEvery project doc has atomic checklist items. Not "build the API" — that's too vague. Instead:
[ ] Add TraceRelationship and TraceRelationshipType in @traces/shared[ ] Expose relatedTo?: TraceRelationship on shared trace read types[ ] Map flat DB fields to nested shared relatedTo shape in API responses[ ] Add returns validators to all public queries touchedThese are concrete enough that an AI agent (or a human) can tick them off without ambiguity.
A golden rule: don't ship API + CLI + frontend changes in the same release unless explicitly permitted.
For example, the Share-to-Traces Skills project had four separate releases:
Each is revertible independently. If a CLI bug is found, you revert Release B without touching the API or frontend.
Some projects include a "failing test spike" phase — a branch with tests that intentionally fail. This locks in the expected behavior before implementation details are finalized.
From the Baton project:
"This phase is allowed to be a non-mergeable spike branch with failing tests."
This is a contract-first approach. Once the tests describe the desired behavior, the implementation becomes a matter of making them green.
When resuming a project after a break, the project doc and worktree location make it trivial to pick up where you left off. The doc is the baton. It contains:
This means weeks can pass between sessions on a project, and you can resume without re-reading the entire codebase.
Every project doc ends with exact verification commands:
# Run feed testscd /Users/tarunsachdeva/code/traces/apibun test tests/v1/feed.test.ts --env-file .env.local
# Manual verificationcurl http://localhost:3211/v1/feedcurl -H "Authorization: Bearer <token>" http://localhost:3211/v1/feedThere's no ambiguity about "how do we know this works?" The answer is in the doc.
When we started the Namespace Improvements project, the first thing we did was create docs/projects/namespace-improvements.md with locked decisions ("invite expiry: 7 days", "session switching mutates existing session"). Then we created a worktree at ~/code/traces-worktrees/feat-org-namespaces. Then we wrote the schema and shared types (PR #61). Then session switching with 20 tests (PR #62). Then invites with 41 tests (PR #63). Each PR was reviewed, merged, and the next was rebased. The frontend UI came last (PR #117), 6 PRs after the API work started.
The result: a complex feature (multi-tenant namespaces with invites, roles, and org creation) shipped incrementally, with no big-bang releases, and every intermediate state was deployable.
These aren't arbitrary rules. They emerge from a few core beliefs:
If you're building something with AI agents as teammates, this structure is even more important. Agents need context. A well-maintained project doc is context they can read and act on. A clean worktree is a sandbox they can work in without fear. Atomic phases are tasks they can complete. And stacked PRs are contributions they can make without overwhelming your main branch.
This is how we build Traces. If you're working on something similar, steal what works and ignore what doesn't. The best process is the one you actually use.
# Run feed testscd /Users/tarunsachdeva/code/traces/apibun test tests/v1/feed.test.ts --env-file .env.local
# Manual verificationcurl http://localhost:3211/v1/feedcurl -H "Authorization: Bearer <token>" http://localhost:3211/v1/feed