Summarize large project workflow in Traces
Public
Summarize large project workflow in Traces
Agent
OpenCode
Model
Kimi-K2.6
Started
May 25, 2:51 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/tracestotal 752
drwxr-xr-x 26 tarunsachdeva staff 832 May 23 23:36 .
drwxr-xr-x 19 tarunsachdeva staff 608 May 10 21:04 ..
drwxr-xr-x@ 3 tarunsachdeva staff 96 Feb 6 16:39 .agents
drwxr-xr-x@ 4 tarunsachdeva staff 128 Apr 14 13:36 .claude
-rw-r--r--@ 1 tarunsachdeva staff 374 May 19 16:26 .dockerignore
-rw-r--r--@ 1 tarunsachdeva staff 8196 Mar 19 07:45 .DS_Store
drwxr-xr-x 21 tarunsachdeva staff 672 May 24 22:50 .git
drwxr-xr-x 4 tarunsachdeva staff 128 Apr 4 11:03 .github
-rw-r--r--@ 1 tarunsachdeva staff 784 May 5 11:19 .gitignore
drwxr-xr-x@ 8 tarunsachdeva staff 256 Apr 12 12:58 .opencode
drwxr-xr-x@ 4 tarunsachdeva staff 128 May 5 11:19 .vscode
drwxr-xr-x@ 11 tarunsachdeva staff 352 May 21 22:37 agent-service
-rw-r--r--@ 1 tarunsachdeva staff 4453 May 5 11:19 AGENTS.md
drwxr-xr-x 13 tarunsachdeva staff 416 May 12 17:57 api
-rw-r--r--@ 1 tarunsachdeva staff 1039 May 5 11:19 biome.json
-rw-r--r--@ 1 tarunsachdeva staff 341752 May 23 23:36 bun.lock
lrwxr-xr-x@ 1 tarunsachdeva staff 9 Feb 6 16:39 CLAUDE.md -> AGENTS.md
drwxr-xr-x 20 tarunsachdeva staff 640 May 21 22:35 cli
drwxr-xr-x 21 tarunsachdeva staff 672 May 23 18:17 docs
drwxr-xr-x 33 tarunsachdeva staff 1056 May 12 17:57 frontend
drwxr-xr-x@ 13 tarunsachdeva staff 416 Apr 29 17:38 node_modules
-rw-r--r--@ 1 tarunsachdeva staff 1858 May 21 22:37 package.json
drwxr-xr-x 4 tarunsachdeva staff 128 Apr 29 17:38 packages
-rw-r--r--@ 1 tarunsachdeva staff 2254 May 5 11:19 README.md
drwxr-xr-x@ 8 tarunsachdeva staff 256 May 5 11:19 scripts
drwxr-xr-x@ 4 tarunsachdeva staff 128 Apr 15 12:01 skills
Let 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"11x-api-key-cli-auth
11x-fixes
11x-generalize-override-directory
11x-generalize-trace-hints
add-handover-skill
aggregated-analytics
auto-research-adapters
bring-realtime-back
chore-draft-pr-skips
chore-revert-api-deploy-large-index-delete
clear-search-columns
cli-create-org
cli-memory-leaks
cli-search-tool
codex-backup-demo
codex-cli-directory-column-width
codex-demo
codex-dependabot-rollup
codex-fix-release-codesign-check
codex-landing-page-copy
codex-shopify-demo
codex-update-billing-docs
convex-scaling-tests
create-namespace-via-cli
docker-kits
docs-cli-api-key-auth
docs-cursor-global-db
docs-readme-traces-setup
docs-test-flake-skill
droid-integration
drop-search-columns
feat-admin-analytics-dashboard-frontend
feat-admin-shadcn-charts-fix
feat-amp-adapter
feat-analytics-honesty-tests
feat-antigravity-adapter
feat-api-key-auth
feat-btw
feat-cli-agent-hardening
feat-cli-privacy-namespace-refresh
feat-cli-share-api-key-token
feat-cli-trace-index-rebuild
feat-cline-adapter
feat-conductor-adapter
feat-copilot-adapter
feat-dev-branch-indicator
feat-devin-adapter
feat-discover-page
feat-docs
feat-docs-getting-started
feat-download-as-skill-file
feat-github-integration-ux-polish
feat-grok-adapter
feat-hermes-adapter
feat-internal-analytics-dashboard-api
feat-message-timing-capture
feat-message-timing-capture-only
feat-model-pages
feat-openclaw-adapter
feat-org-billing-spec
feat-privacy-frontend
feat-raw-agent-event-pipeline
feat-repo-discovery
feat-resume-trace-session
feat-search
feat-sentry-setup
feat-t3-code-adapter
feat-trace-namespace-transfer
feed-avatar-link-fix
fix-217-sqlite-eventstore-init-corruption
fix-482-targeted-scrub-backfill
fix-adapter-directory-tests
fix-ai-summary-post-processing
fix-analytics
fix-api-deploy-large-index-delete
fix-api-test-flake-hardening
fix-autoupdate
fix-backfill-message-counts-timeout
fix-cli-namespace-command-tests
fix-cline-session-storage
fix-codex-tool-events
fix-empty-sessions
fix-eventstore-runtime-sqlite-recovery
fix-git-not-saving
fix-github-deleted-install-state
fix-github-notes-pr-refresh
fix-github-setup-copy
fix-http-cli-limit-500
fix-namespace-env-default
fix-namespace-export-oom-status
fix-namespace-exports-oom
fix-namespace-trace-privacy-issues
fix-openclaw-agent-color
fix-org-switcher-header-dropdown
fix-pi-session-lifecycle-hooks
fix-pi-share-skill-collision
fix-post-commit-hook-docker
fix-pr-only-ci-concurrency
fix-pre-push-hook-recursion
fix-profile-trace-pagination
fix-reset-dev-convex-admin-key
fix-search
fix-test-cleanup-pr
fix-trace-message-ordering
fix-worktree-trace-dir-matching
handoff-resume
idiotmatic-skills
improved-search-remove-legacy-schema
improved-vector-search
investigate-cursor-docker-wal-repro
investigate-git-hooks-worktrees
jsonl-download
kanban-view
kill-search
link-installation-to-namespace
message-deeplinking
namespace-export
new-contribution-graph
onboarding-1-api-feed-filter
onboarding-breakdown
onboarding-cleanup-ui
onboarding-core
onboarding-nav-cta
onboarding-polish
perf-cli-startup-memory
pin-bun-release-ci
pr-471
project-baton
project-baton-pr1
project-baton-pr2
project-baton-pr3
project-baton-pr4
reduce-ai-analysis-time
release-smoke-tests
remove-duplicate-notes-refspec-ensure
revert-github-notes-pr-refresh
security-api-trace-isolation-and-limits
sentry-cli-4
slate-adapter
spike-convex-aggregate
spike-evals-skills-integration
spike-langwatch-study
structured-summary
structured-summary-api-layer
structured-summary-trace-doctor
test-github-notes-pr-refresh-e2e
test-worktree
trace-download-huggingface
trace-download-jsonl
trace-upload-finalization
traces-dark-mode
traces-sync-refactor
traces-worktrees
tui-onboarding
update-amp-adapter
update-trace-format-cli
verify-release-artifacts
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 -30/Users/tarunsachdeva/code/traces/docs/research/agent-hooks-plan.md:In a normal repo this is `.git/traces-active.json`. In a linked worktree it's `.git/worktrees/<name>/traces-active.json` -- each worktree gets its own file because different worktrees have different active sessions. This matches how `traces-pending.json` already works (written per-worktree via `--git-dir`).
/Users/tarunsachdeva/code/traces/docs/research/agent-hooks-plan.md:The git hooks already use `--git-dir` for per-worktree state (`traces-pending.json`) and `--git-common-dir` for shared hook scripts. The active session file follows the same split: per-worktree data, shared hook scripts.
/Users/tarunsachdeva/code/traces/docs/research/agent-hooks-plan.md:- Find the per-worktree git dir (`git rev-parse --git-dir`) -- returns `.git` for normal repos or `.git/worktrees/<name>` for linked worktrees
/Users/tarunsachdeva/code/traces/docs/research/agent-hooks-plan.md:- Resolve subdirectories to the worktree root before looking up traces
/Users/tarunsachdeva/code/traces/docs/research/agent-hooks-plan.md:Claude Code's settings.json lives at the worktree root (not inside `.git/`), so in a linked worktree it's at the worktree's own root, not the main worktree. This is correct -- each worktree can have its own `.claude/settings.json`. The hook command itself resolves `--git-dir` at runtime to find the right `traces-active.json` for the current worktree.
/Users/tarunsachdeva/code/traces/docs/research/agent-hooks-plan.md:In `hook-prepare-commit-msg.ts`, before the current `listTraces` call, check for `<git-dir>/traces-active.json`. The hook already resolves `gitDir` via `git rev-parse --git-dir`, which returns the per-worktree path. If the file exists and has sessions, use those trace IDs directly instead of spawning `traces list`. Fall back to the current behavior if the file doesn't exist (hooks not installed, or session-start didn't fire).
/Users/tarunsachdeva/code/traces/docs/research/agent-hooks-plan.md:This works in linked worktrees because `gitDir` is already worktree-specific -- the same pattern `traces-pending.json` uses today.
/Users/tarunsachdeva/code/traces/docs/research/agent-hooks-plan.md:- `docs/git-integration.md` -- add agent hooks section explaining the new flow (session-start -> prompt-submitted -> agent-done -> post-commit), how it replaces the timestamp search, the active sessions file format, and worktree behavior. Update the existing git hooks section to describe the fast path when active sessions are available.
/Users/tarunsachdeva/code/traces/docs/research/entireio-cli-hooks.md:3. `prepare-commit-msg`: find active sessions for this worktree, append `Entire-Checkpoint: <id>` trailer
/Users/tarunsachdeva/code/traces/docs/convex-update-runbook.md:### 1. Create a worktree
/Users/tarunsachdeva/code/traces/docs/convex-update-runbook.md:bash scripts/new-worktree.sh feat/convex-self-hosted-update --new
/Users/tarunsachdeva/code/traces/docs/convex-update-runbook.md:cd ../traces-worktrees/feat-convex-self-hosted-update
/Users/tarunsachdeva/code/traces/docs/git-integration.md:The active sessions file is per-worktree (stored in the git dir, not the working tree), so linked worktrees with different sessions don't conflict. Entries older than 24 hours are pruned automatically.
/Users/tarunsachdeva/code/traces/docs/projects/cli-startup-memory-experiments.md:- Perf worktree experiments that disable background sync, background refresh, or
/Users/tarunsachdeva/code/traces/docs/projects/sentry-setup.md:- [x] Create isolated git worktree for Sentry work.
/Users/tarunsachdeva/code/traces/docs/projects/namespace-improvements.md:# Worktree: ~/src/traces-worktrees/feat-org-namespaces
/Users/tarunsachdeva/code/traces/docs/projects/namespace-improvements.md:~/src/traces-worktrees/feat-org-namespaces
/Users/tarunsachdeva/code/traces/docs/projects/namespace-improvements.md:Main repo at `~/src/traces`. The worktree is used for all org-ns branch work.
/Users/tarunsachdeva/code/traces/docs/projects/cli-tui-componentize.md:- Run `bun run dev` in the worktree to verify each phase
/Users/tarunsachdeva/code/traces/docs/projects/project-baton.md:- `/Users/tarunsachdeva/code/traces-worktrees/project-baton`
/Users/tarunsachdeva/code/traces/docs/projects/cli-indexed-trace-discovery.md:- [x] Gracefully skip stale traces whose adapter ID is not registered in this worktree.
/Users/tarunsachdeva/code/traces/docs/projects/cli-indexed-trace-discovery.md:- [x] Ship as default behavior in this worktree branch.
/Users/tarunsachdeva/code/traces/docs/projects/handoff-resume.md:- [x] Created worktree: `handoff-resume`.
/Users/tarunsachdeva/code/traces/docs/projects/handoff-resume.md:- workspace/worktree info
/Users/tarunsachdeva/code/traces/docs/projects/handoff-resume.md:### c) Workspace/worktree state is explicit
/Users/tarunsachdeva/code/traces/docs/projects/handoff-resume.md:This is a strong precedent for treating git/worktree info as **state**, not just presentation metadata.
Now 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.
Session shared successfully!
URL: https://traces.com/s/jn7cv65nqg078jp61bgs4h1my587dtcr
Trace: ses_1a2f434d2ffeXFTzv5FUA2fxe8 (opencode)
Selected by: env-hintThe 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