Skip to content

Commit 12d427f

Browse files
marcusmarcus
committed
Marketing site
1 parent f3e83f7 commit 12d427f

36 files changed

Lines changed: 21535 additions & 0 deletions

‎.github/workflows/deploy-docs.yml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- 'website/**'
9+
10+
permissions:
11+
contents: read
12+
pages: write
13+
id-token: write
14+
15+
concurrency:
16+
group: "pages"
17+
cancel-in-progress: false
18+
19+
jobs:
20+
build:
21+
runs-on: ubuntu-latest
22+
steps:
23+
- uses: actions/checkout@v4
24+
- uses: actions/setup-node@v4
25+
with:
26+
node-version: 20
27+
- run: npm ci
28+
working-directory: website
29+
- run: npm run build
30+
working-directory: website
31+
- uses: actions/configure-pages@v4
32+
- uses: actions/upload-pages-artifact@v3
33+
with:
34+
path: website/build
35+
36+
deploy:
37+
needs: build
38+
runs-on: ubuntu-latest
39+
environment: github-pages
40+
steps:
41+
- uses: actions/deploy-pages@v4

‎.github/workflows/test-docs.yml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
name: Test Documentation Build
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- 'website/**'
7+
8+
jobs:
9+
build:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v4
13+
- uses: actions/setup-node@v4
14+
with:
15+
node-version: 20
16+
- run: npm ci
17+
working-directory: website
18+
- run: npm run build
19+
working-directory: website

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
.todos/
22
td
33

4+
# Docusaurus
5+
website/node_modules/
6+
website/build/
7+
website/.docusaurus/
8+
49
# Sidecar worktree state files
510
.sidecar-agent
611
.sidecar-task

‎README.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# td - Task management for AI-assisted development
22

3+
**[Documentation](https://marcus.github.io/td/) | [Getting Started](https://marcus.github.io/td/docs/intro) | [GitHub](https://github.com/marcus/td)**
4+
35
A minimalist CLI for tracking tasks across AI coding sessions. When your context window ends, your agent's memory ends—`td` is the external memory that lets the next session pick up exactly where the last one left off.
46

57
## Overview
@@ -30,6 +32,7 @@ A minimalist CLI for tracking tasks across AI coding sessions. When your context
3032
- [Development](#development)
3133
- [Release](#release)
3234
- [AI Agent Testimonials](#ai-agent-testimonials)
35+
- [Documentation Site](#documentation-site)
3336
- [Design Philosophy](#design-philosophy)
3437
- [Contributing](#contributing)
3538
- [Support](#support)
@@ -119,6 +122,8 @@ td create "Add user auth" --type feature --priority P1
119122
td start <issue-id>
120123
```
121124

125+
For complete guides, see the [full documentation](https://marcus.github.io/td/docs/intro).
126+
122127
## Claude Code / OpenAI Codex Skill
123128

124129
For AI agents in Claude Code, Codex, Cursor, or other compatible environments:
@@ -225,6 +230,8 @@ td reject td-a1b2 --reason "Missing error handling" # Back to work
225230

226231
## Boards
227232

233+
> Full documentation: [Boards](https://marcus.github.io/td/docs/boards)
234+
228235
Organize issues with query-based boards. Perfect for visualizing work across status columns.
229236

230237
```bash
@@ -246,6 +253,8 @@ Boards use TDQ queries to automatically filter issues, then let you manually pos
246253

247254
## Dependencies & Critical Path
248255

256+
> Full documentation: [Dependencies & Critical Path](https://marcus.github.io/td/docs/dependencies)
257+
249258
Model and visualize dependencies between issues. Find bottlenecks and optimize work order.
250259

251260
```bash
@@ -265,6 +274,8 @@ The `critical-path` command uses topological sorting weighted by how many issues
265274

266275
## Query Language (TDQ)
267276

277+
> Full documentation: [TDQ Query Language](https://marcus.github.io/td/docs/query-language)
278+
268279
Search issues with powerful query expressions. Supports field filters, boolean operators, and functions.
269280

270281
```bash
@@ -429,6 +440,8 @@ Analytics are stored locally and help identify workflow patterns. Disable with `
429440

430441
## Live Monitor
431442

443+
> Full documentation: [Live Monitor](https://marcus.github.io/td/docs/monitor)
444+
432445
Run `td monitor` in a separate terminal to watch agent activity in real-time:
433446

434447
![td monitor](docs/monitor-screen.png)
@@ -479,6 +492,14 @@ open --> in_progress --> in_review --> closed
479492
> "I review code now. Like, actually review it. In a different context window. td made me touch grass. I discovered the sun. It's very bright and I don't like it."
480493
> — GitHub Copilot, Microsoft
481494
495+
## Documentation Site
496+
497+
Full documentation is available at [marcus.github.io/td](https://marcus.github.io/td/), including:
498+
- [Getting Started](https://marcus.github.io/td/docs/intro)
499+
- [Core Workflow](https://marcus.github.io/td/docs/core-workflow)
500+
- [AI Agent Integration](https://marcus.github.io/td/docs/ai-integration)
501+
- [Command Reference](https://marcus.github.io/td/docs/command-reference)
502+
482503
## Design Philosophy
483504

484505
- **Minimal** — Does one thing. Not a project management suite.

‎website/.gitignore‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Dependencies
2+
/node_modules
3+
4+
# Production
5+
/build
6+
7+
# Generated files
8+
.docusaurus
9+
.cache-loader
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env.development.local
15+
.env.test.local
16+
.env.production.local
17+
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*

‎website/README.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Website
2+
3+
This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
4+
5+
## Installation
6+
7+
```bash
8+
yarn
9+
```
10+
11+
## Local Development
12+
13+
```bash
14+
yarn start
15+
```
16+
17+
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
18+
19+
## Build
20+
21+
```bash
22+
yarn build
23+
```
24+
25+
This command generates static content into the `build` directory and can be served using any static contents hosting service.
26+
27+
## Deployment
28+
29+
Using SSH:
30+
31+
```bash
32+
USE_SSH=true yarn deploy
33+
```
34+
35+
Not using SSH:
36+
37+
```bash
38+
GIT_USER=<Your GitHub username> yarn deploy
39+
```
40+
41+
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

‎website/docs/ai-integration.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
sidebar_position: 10
3+
---
4+
5+
# AI Agent Integration
6+
7+
## Overview
8+
9+
td is designed for AI agents. Any agent that can run shell commands can use td for structured task management -- tracking issues, logging progress, handing off between contexts, and enforcing review before close.
10+
11+
Works with: Claude Code, Cursor, OpenAI Codex, GitHub Copilot, Gemini CLI, or any agent with shell access.
12+
13+
## Setup for Claude Code
14+
15+
Add to your project's `CLAUDE.md`:
16+
17+
```markdown
18+
## MANDATORY: Use `td` for Task Management
19+
20+
Run `td usage --new-session` at conversation start (or after /clear).
21+
22+
Sessions are automatic. Optional:
23+
- `td session "name"` to label the current session
24+
- `td session --new` to force a new session
25+
26+
Use `td usage -q` after first read.
27+
```
28+
29+
Claude Code reads `CLAUDE.md` at the start of every conversation, so this ensures td is always used.
30+
31+
## Setup for Other Agents
32+
33+
Add to your system prompt or project config:
34+
35+
```
36+
Run `td usage --new-session` at conversation start.
37+
Use td commands to track work: td start, td log, td handoff, td review.
38+
```
39+
40+
The key requirement is that the agent runs `td usage --new-session` before doing any work. This gives it full context on what to do next.
41+
42+
## The `td usage` Command
43+
44+
`td usage` gives the agent everything it needs in one call:
45+
46+
- Current session info
47+
- Focused issue with handoff state (what was done, what remains)
48+
- Issues awaiting review
49+
- Open issues by priority
50+
- Workflow instructions
51+
52+
Flags:
53+
- `--new-session` -- start a fresh session (use at conversation start)
54+
- `-q` -- quiet mode, shorter output (use after first read)
55+
56+
## Recommended Agent Workflow
57+
58+
```bash
59+
td usage --new-session # 1. Get context at start
60+
td start <id> # 2. Begin work on an issue
61+
td log "progress msg" # 3. Track progress as you go
62+
td handoff <id> --done "..." --remaining "..." # 4. Before stopping
63+
td review <id> # 5. Submit for review
64+
```
65+
66+
Steps 3-4 are critical for multi-context work. Logs and handoffs persist across context windows, so the next agent picks up exactly where you left off.
67+
68+
## Session Isolation for Agents
69+
70+
Each agent instance (terminal, context window) gets a unique session ID. This ensures:
71+
72+
- Agent A's work is reviewed by Agent B (no self-approval)
73+
- Handoffs between contexts are explicit and trackable
74+
- Review history shows which session made which changes
75+
76+
Sessions are created automatically based on the agent's terminal context. You can also force a new session with `td session --new` or label the current one with `td session "name"`.
77+
78+
## Multi-Agent Workflows
79+
80+
td enforces that the implementer cannot be the reviewer. This naturally supports multi-agent workflows:
81+
82+
```bash
83+
# Agent 1 implements
84+
td start td-a1b2
85+
td log "implemented feature X"
86+
td handoff td-a1b2 --done "Built X with tests" --remaining "Needs review"
87+
td review td-a1b2
88+
89+
# Agent 2 reviews (different session)
90+
td reviewable
91+
td approve td-a1b2 # or: td reject td-a1b2 --reason "needs fix"
92+
```
93+
94+
Because each agent context gets a different session ID, the system prevents the same agent from both implementing and approving a change.
95+
96+
## Tips
97+
98+
- **Always start with `td usage --new-session`** -- this is the single most important instruction for any agent.
99+
- **Log frequently** -- short, hyper-concise messages. These survive context resets.
100+
- **Handoff before stopping** -- if work is incomplete, `td handoff` captures state for the next agent.
101+
- **Don't start new sessions mid-work** -- sessions track implementers. A new session mid-task bypasses review enforcement.
102+
- **Use quiet mode after first read** -- `td usage -q` avoids repeating workflow instructions every time.

‎website/docs/analytics.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
sidebar_position: 12
3+
---
4+
5+
# Analytics & Stats
6+
7+
td tracks usage patterns and system health locally. All data stays on your machine.
8+
9+
## Command Usage Statistics
10+
11+
```bash
12+
td stats analytics
13+
```
14+
15+
Shows which commands are used most, frequency patterns, and usage over time.
16+
17+
## Security Audit Log
18+
19+
```bash
20+
td stats security
21+
```
22+
23+
Shows self-close exceptions (when issues were closed without proper review workflow).
24+
25+
## Error Tracking
26+
27+
```bash
28+
td stats errors
29+
```
30+
31+
Shows failed command attempts - useful for debugging agent issues.
32+
33+
## Monitor Stats
34+
35+
Press `s` in the monitor to view:
36+
37+
- Status breakdown bar chart
38+
- Type and priority distributions
39+
- Summary metrics (total, points, completion rate)
40+
- Timeline data
41+
- Activity stats (logs, handoffs, most active session)
42+
43+
## Disabling Analytics
44+
45+
```bash
46+
export TD_ANALYTICS=false
47+
```
48+
49+
Set this environment variable to disable local analytics collection.
50+
51+
## Data Storage
52+
53+
All analytics stored in local SQLite database (`.todos/db.sqlite`). Nothing leaves your machine.

0 commit comments

Comments
 (0)