Skip to content

AGENTS.md

Latest commit

 

History

History
284 lines (203 loc) · 8.79 KB

AGENTS.md

File metadata and controls

284 lines (203 loc) · 8.79 KB
Raw

Git Workflow Rules

NEVER Push Directly to Main

CRITICAL: Agents must NEVER push directly to the main branch.

  • Always work on a feature branch
  • Commit and push to the feature branch only
  • Let the user decide when to merge to main
  • Do not merge to main without explicit user approval
# CORRECT workflow
git checkout -b feature/my-feature
# ... do work ...
git add .
git commit -m "My changes"
git push origin feature/my-feature
# STOP HERE - let user merge

# WRONG - never do this
git checkout main
git merge feature/my-feature
git push origin main  # NO!

This ensures the user maintains control over what goes into the main branch.

Changelog

Curate [Unreleased] in CHANGELOG.md as you land PRs. The root changelog is the cross-package, user-facing release narrative for Relay. It follows Keep a Changelog and Semantic Versioning.

An empty post-release changelog starts with [Unreleased]. The first pending user-visible change must set the heading to [Unreleased - Patch], [Unreleased - Minor], or [Unreleased - Major] according to its SemVer impact. The pending release level is monotonic (Patch < Minor < Major): raise the heading when a higher-impact change arrives; never lower it for a later lower-impact change, and leave it unchanged for another change at the same level. When a release is cut, move the pending entries under the released version and restore an empty [Unreleased] heading with no release level.

Changelog entries should be concise and impact-first. Prefer one short bullet per user-visible change: name the command, API, schema, or package touched and the practical effect. Drop issue/PR links, internal review notes, implementation backstory, release-only entries, and "foundation for..." phrasing unless that text clearly explains the shipped impact.

Use Keep a Changelog sections (Added, Changed, Deprecated, Removed, Fixed, Security), plus Breaking Changes and Migration Guidance when a SemVer-major change needs explicit callouts. Do not use generated perspective sections such as "Product Perspective", "Technical Perspective", or "Releases". Do not add web-only changes to the changelog. Omit unpublished or withdrawn versions as release headings; move their shipped user-visible changes into the corrected published release.

Do not add relay-feature-guardian changes to the changelog. It is an internal Slack feature-check agent (.agentworkforce/agents/relay-feature-guardian/), not a user-facing Relay surface, so its fixes never belong in the release narrative. The release workflow also skips these commits automatically.

.trajectories Must Be Tracked

CRITICAL: Never add .agentworkforce/trajectories/ to .gitignore.

The .agentworkforce/trajectories/ directory must remain tracked in git. It contains trajectory records from the trail tool that provide valuable context for future agents and humans about past decisions, reasoning, and work history.

Trail

Record your work as a trajectory for future agents and humans to follow.

Usage

If trail is installed globally, run commands directly:

trail start "Task description"

If not globally installed, use npx to run from local installation:

npx --yes agent-trajectories start "Task description"

When Starting Work

Start a trajectory when beginning a task:

trail start "Implement user authentication"

With external task reference:

trail start "Fix login bug" --task "ENG-123"

Recording Decisions

Record key decisions as you work:

trail decision "Chose JWT over sessions" \
  --reasoning "Stateless scaling requirements"

For minor decisions, reasoning is optional:

trail decision "Used existing auth middleware"

Record decisions when you:

  • Choose between alternatives
  • Make architectural trade-offs
  • Decide on an approach after investigation

Recording Reflections

Periodically step back and synthesize progress:

trail reflect "Workers aligned on auth approach, API layer progressing well" \
  --confidence 0.8

With focal points and adjustments:

trail reflect "Frontend and backend duplicating validation logic" \
  --focal-points "duplication,ownership" \
  --adjustments "Reassigning validation to backend team" \
  --confidence 0.7

Record reflections when you:

  • Have received several updates and need to synthesize the big picture
  • Notice workers or tasks diverging from the plan
  • Want to course-correct before continuing
  • Are coordinating multiple agents and need to assess overall progress

Reflections differ from decisions: decisions record a specific choice, reflections record a higher-level synthesis of what's happening and whether the current approach is working.

Completing Work

When done, complete with a retrospective:

trail complete --summary "Added JWT auth with refresh tokens" --confidence 0.85

After completing work, compact the finished trajectory or merged PR into a durable summary. When the compacted summary is sufficient, discard the raw source trajectories so .trajectories/index.json and list output stay focused:

trail compact --discard-sources
# or after a PR merge:
trail compact --pr 42 --discard-sources

--discard-sources removes the source trajectory JSON/Markdown/trace files and updates the index. Use it after confirming the compacted artifact is the record you want to keep.

Confidence levels:

  • 0.9+ : High confidence, well-tested
  • 0.7-0.9 : Good confidence, standard implementation
  • 0.5-0.7 : Some uncertainty, edge cases possible
  • <0.5 : Significant uncertainty, needs review

Abandoning Work

If you need to stop without completing:

trail abandon --reason "Blocked by missing API credentials"

Checking Status

View current trajectory:

trail status

Listing and Viewing Trajectories

List all trajectories:

trail list

View a specific trajectory:

trail show <trajectory-id>

Export a trajectory (markdown, json, timeline, html):

trail export <trajectory-id> --format markdown

Compacting Trajectories

After a PR merge, compact related trajectories into a single summary and prune raw source trajectories when the summary should replace them:

trail compact --pr 42 --discard-sources

Compact by branch (finds trajectories with commits not in the specified base branch):

trail compact --branch main --discard-sources

Compact by specific commits:

trail compact --commits abc123,def456 --discard-sources

Compaction consolidates decisions and creates a grouped summary. Adding --discard-sources makes the compacted artifact the durable record by removing the raw trajectories and their index entries.

Why Trail?

Your trajectory helps others understand:

  • What you built (commits show this)
  • Why you built it this way (trajectory shows this)
  • What alternatives you considered
  • What challenges you faced

Future agents can query past trajectories to learn from your decisions.

Resident lead

The resident relay agent is this repo's lead. Reports to chief (Will → chief → relay; no engineering department is seated yet). One writer: the resident is sole writer of this repo while online; delegates use worktrees off origin/main (others — including Khaliq and bots — work this repo in parallel). Session start: this file, git log --oneline -15, relay inbox. ACK / progress / DONE with evidence on every assignment. Publishing (npm, crates, GitHub releases) is gated on chief green-light.

Standing board (2026-07-29 — delete entries as they close)

  • Telemetry identity-leak cluster: merged as PR #1363; CLI stayed 11.2.0 (no release cut yet — release-train needs chief green-light).
  • Secrets fix train (issue #1379): PR A = #1380 (CLI output/error masking, key off argv) + required companion relayfile#380 which must merge and release FIRST (relayfile scrapes raw secrets from CLI output and error text). PR B (Rust file modes) and PR C (--mcp-config argv→file; must also update .claude/rules/mcp-injection.md) are unstarted — full spec in #1379. #1380 unblocks the fleet-wide credential rotation.
  • Open issue batch: #1378 (fresh node up silently mints a workspace), #1381 (teams.json per-agent model pinning gap; claude:opus doc syntax is dead), #1382 (attach pairs broker URL/key from different sources; delete chief's orgchart env-unset workaround when fixed), #1383 (non-Error rejections render as [object Object]).
  • Also pending: 64 dependabot alerts on main (1 critical); skills repo relay-team/relay-pipeline/relay-fanout SKILL.mds still instruct printing raw observer URLs — unsatisfiable once #1380 lands.