feat(v0.6): AGENTS.md seed + CLAUDE.md shim + handoff + context-archive scaffold
New workspaces get:
- AGENTS.md (always): canonical agent instructions — handoff workflow,
notes-archive convention (~300-500 line trigger), cross-workspace
discovery, do-not-touch warnings. Project variant adds workspace-
structure and git-conventions sections.
- CLAUDE.md shim (claude type only per v0.6 spec §6 — opencode shim
deferred until its instruction-file convention is verified).
- handoff.md: minimal current-state template the agent updates per
session.
- context/notes-archive/.gitkeep: directory pinned for git tracking,
ready for the agent to populate per the archive convention.
seed.ClaudeMD and seed.ClaudeMDProject removed — no callers remain.
Existing workspaces are NOT modified; this is strictly a ctask-new code
path. The seed-wins overlay rule still applies — a user seed dir's
AGENTS.md/CLAUDE.md overrides the built-in.
This commit is contained in:
@@ -0,0 +1,130 @@
|
||||
package seed
|
||||
|
||||
// AgentsMD returns the canonical AGENTS.md content for a new workspace.
|
||||
// This is the single source of truth for agent-facing instructions in
|
||||
// v0.6+. Agent-specific files (CLAUDE.md, etc.) become thin shims
|
||||
// pointing back here. Per v0.6 spec §6.
|
||||
//
|
||||
// isProject controls a small set of project-specific additions
|
||||
// (workspace-structure section, git conventions).
|
||||
func AgentsMD(isProject bool) string {
|
||||
base := `# Workspace Instructions
|
||||
|
||||
This workspace uses ctask. AGENTS.md is the canonical instruction file
|
||||
for agents working here. Agent-specific files (CLAUDE.md, etc.) are
|
||||
thin shims that defer to this document.
|
||||
|
||||
## Session Workflow
|
||||
|
||||
- Read handoff.md first when starting a session. It carries the
|
||||
current-state briefing: last completed work, immediate next step,
|
||||
blockers, and files to inspect first.
|
||||
- Update notes.md with decisions, design rationale, and observations
|
||||
during the session.
|
||||
- Update handoff.md before ending the session so the next agent (or
|
||||
the next instance of you) can pick up cleanly. Keep it short and
|
||||
current -- handoff.md is not a history file.
|
||||
|
||||
## Notes Archival
|
||||
|
||||
When notes.md becomes too large to scan comfortably (roughly 300-500
|
||||
lines or 10-20 KB), archive older completed-phase sections:
|
||||
|
||||
1. Create a new file: context/notes-archive/YYYY-MM-DD-topic.md
|
||||
2. Move the older sections into it, preserving them exactly.
|
||||
3. Add a pointer at the top of notes.md:
|
||||
"Older notes archived in context/notes-archive/YYYY-MM-DD-topic.md"
|
||||
4. Do not delete or summarize-away historical notes as the only
|
||||
preservation mechanism.
|
||||
5. Keep handoff.md short and current. It is not a history file.
|
||||
|
||||
## Cross-Workspace Context
|
||||
|
||||
Related work may exist in other ctask workspaces. Use:
|
||||
|
||||
ctask list --all discover all workspaces, including archived
|
||||
ctask info <workspace> view metadata and status
|
||||
ctask notes <workspace> read another workspace's notes.md
|
||||
ctask path <workspace> get the filesystem path
|
||||
|
||||
Treat other workspaces as read-only unless the user explicitly asks
|
||||
otherwise.
|
||||
|
||||
## Do Not Touch
|
||||
|
||||
- Do not modify .ctask/ -- those are ctask internals (lease, manifests,
|
||||
session summary, write lock).
|
||||
- Do not edit task.yaml's metadata fields by hand. ctask owns them.
|
||||
`
|
||||
if !isProject {
|
||||
return base + `
|
||||
## File Placement (task workspace)
|
||||
|
||||
- Source code and scripts -> workspace root or src/
|
||||
- Documentation, summaries, reports -> docs/
|
||||
- Deliverables and exports -> output/
|
||||
- Reference material and imported files -> context/
|
||||
- Do not place non-code outputs in the workspace root.
|
||||
`
|
||||
}
|
||||
return base + `
|
||||
## Workspace Structure (project workspace)
|
||||
|
||||
This workspace uses ctask's project layout. The workspace root contains
|
||||
ctask management files; your project code lives in the project
|
||||
subdirectory (named after the workspace slug). When working on project
|
||||
code, operate inside the project subdirectory.
|
||||
|
||||
- Workspace root: ctask metadata, session logs, notes, reference material
|
||||
- Project subdirectory: source code, project-specific configuration
|
||||
- context/: reference material and imported specs (workspace level)
|
||||
- output/: deliverables and exports (workspace level)
|
||||
- logs/: session logs (managed by ctask)
|
||||
|
||||
## Git Conventions
|
||||
|
||||
This workspace uses a single git repository initialized at the workspace
|
||||
root. The project subdirectory and all its contents are tracked by this
|
||||
root repo. Do not initialize additional git repositories inside the
|
||||
project subdirectory or elsewhere -- the repo root is the workspace root.
|
||||
`
|
||||
}
|
||||
|
||||
// ClaudeShimMD returns the thin CLAUDE.md generated for new workspaces
|
||||
// whose agent.type is "claude". It exists purely to point Claude Code at
|
||||
// AGENTS.md; canonical instructions live there. Per v0.6 spec §6.
|
||||
func ClaudeShimMD() string {
|
||||
return `<!-- Generated by ctask. Edit AGENTS.md for canonical instructions.
|
||||
This file may be regenerated by future ctask agent-management commands. -->
|
||||
|
||||
# Claude Code Instructions
|
||||
|
||||
This workspace uses AGENTS.md as the canonical agent guidance file.
|
||||
Read AGENTS.md first.
|
||||
|
||||
## Claude-specific notes
|
||||
|
||||
- Use claude CLI conventions for file operations.
|
||||
- Respect the workspace structure described in AGENTS.md.
|
||||
`
|
||||
}
|
||||
|
||||
// HandoffMD returns the minimal handoff.md template seeded into new
|
||||
// workspaces. The agent fills it in at session end; the next session
|
||||
// reads it first. Per v0.6 spec §8.
|
||||
func HandoffMD() string {
|
||||
return `# Handoff
|
||||
|
||||
## Current state
|
||||
|
||||
New workspace. No work completed yet.
|
||||
|
||||
## Next step
|
||||
|
||||
[Describe the task or project goal here.]
|
||||
|
||||
## Files to read first
|
||||
|
||||
- AGENTS.md - workspace instructions and conventions
|
||||
`
|
||||
}
|
||||
Reference in New Issue
Block a user