Job Management

This folder and its subfolders are managed using deepwork_jobs workflows.

Recommended Workflows

• deepwork_jobs/new_job - Full lifecycle: define → implement → test → iterate
• deepwork_jobs/learn - Improve instructions based on execution learnings
• deepwork_jobs/repair - Clean up and migrate from prior DeepWork versions

Directory Structure

.
├── .deepreview        # Review rules for the job itself using Deepwork Reviews
├── AGENTS.md          # This file - project context and guidance
├── job.yml            # Job specification (created by define step)
├── steps/             # Step instruction files (created by implement step)
│   └── *.md           # One file per step
├── hooks/             # Custom validation scripts and prompts
│   └── *.md|*.sh      # Hook files referenced in job.yml
├── scripts/           # Reusable scripts and utilities created during job execution
│   └── *.sh|*.py      # Helper scripts referenced in step instructions
└── templates/         # Example file formats and templates
    └── *.md|*.yml     # Templates referenced in step instructions

Editing Guidelines

1. Use workflows for structural changes (adding steps, modifying job.yml)
2. Direct edits are fine for minor instruction tweaks

Learnings

Agent-space repo root IS the working directory (v2.0.0)

The agent-space repo root contains all files directly (SOUL.md, AGENTS.md, PROJECTS.yaml, etc.) — there is NO notes/ subdirectory. The notes directory seen at /home/agent-drago/notes/ is a symlink FROM the home directory TO the agent-space repo, not a subdirectory within it. See .repos/drago/agent-space/ for the canonical layout.

Submodule is .agents/ directly, not nested (v2.3.0)

The ncrmro/agents submodule lives at .agents/ — NOT .agents/ncrmro/agents/. This matches the Nix flake pattern where .agents is the submodule root.

Symlink paths are relative to symlink location

• .deepwork at repo root → .agents/.deepwork (no ../)
• agents_repo in manifests/modes.yaml → ../.agents (one ../ from manifests/)

Existing repos may already have git initialized

Always check for .git before running git init. Users often pre-create repos on Forgejo with remotes already configured.

Nix dev shell is shared via copies, not symlinks (v2.2.0)

The shared agents repo (ncrmro/agents) provides flake.nix with the dev shell (deepwork, yq, etc.). Each agent-space copies flake.nix and flake.lock from the submodule. Symlinks don't work because Nix flakes require all paths to be tracked in the repo's git tree — symlinks into submodules cause "not tracked by Git" errors. A real .envrc file (use flake) is created for direnv, then direnv allow is run.

AGENTS.md is a symlink, not a generated file (v2.3.0)

AGENTS.md MUST be a symlink to .agents/AGENTS_TEMPLATE.md (the shared template in the submodule). This ensures all agents automatically get template updates when the submodule is updated. The template uses Claude Code @ includes (@SOUL.md, @HUMAN.md, @SERVICES.md, @.agents/ARCHITECTURE.md) which resolve relative to the repo root (where the CLAUDE.md symlink lives). Do NOT generate AGENTS.md as a custom file.

Symlink chain: CLAUDE.md → AGENTS.md → .agents/AGENTS_TEMPLATE.md

Ask before committing in interactive mode

When running interactively (not claude -p), agents MUST ask the user before committing and pushing changes — especially to the shared agents library (.agents/ submodule) which has branch protection on main. Do not auto-commit convention updates, job file changes, or any submodule modifications without explicit user confirmation.

Quality reviews on scaffold step cause timeouts

The scaffold step produces many files (14+). Step-level quality reviews on this many files time out. Reviews are disabled for scaffold — verification is built into the step instructions (step 13).

Convention Sync: .agents/ <-> keystone (v3.0.0)

Conventions live in two locations that must be kept in sync:

• .agents/conventions/ — agent-space submodule (used by compose.sh to build AGENTS.md)
• .repos/ncrmro/keystone/conventions/ — upstream shared library (canonical source)

The wire_mode step includes a sync instruction (step 7) to copy new conventions to keystone.

Out-of-sync conventions (as of 2026-03-19)

These conventions exist in .agents/conventions/ but not yet in keystone:

• process.blocker.md
• process.code-review-ownership.md
• process.deepwork-job.md
• process.refactor.md

Wiring Mechanism (v3.0.0)

This agent space uses archetypes.yaml (not manifests/modes.yaml) for convention wiring. The wire_mode step should update archetypes.yaml at the .agents/ repo root, adding the convention to the appropriate archetype's referenced_conventions or role conventions list.

SSH Key Signing Setup (v3.0.0)

• SSH key signing must be set up for both GitHub and Forgejo during onboarding
• Use Chrome DevTools MCP browser as the primary method for adding signing keys (especially on Forgejo where CLI support is limited)
• Always confirm the agent can log into the web UI before attempting to add SSH keys
• GitHub: gh ssh-key add --type signing works via CLI; browser fallback at github.com/settings/ssh/new
• Forgejo: Use browser at git.ncrmro.com/user/settings/keys — both auth and signing keys managed there

Dependency Validation (v3.0.0)

Every from_step file input must have the corresponding step in dependencies — transitive dependencies through the workflow DAG are not enough for validation.

agentctl requires sudo — use direct commands when running as agent (v3.1.1)

The doctor workflow's check_health step originally used agentctl for all commands, but agentctl requires sudo which isn't available when running as the agent user directly (which is how task-loop sessions and interactive Claude Code sessions work). Use systemctl --user and journalctl --user instead. Direct commands like rbw unlocked, gh auth status, ssh-add -l, and fj whoami also work without agentctl wrappers.

See steps/check_health.md and steps/analyze_logs.md for the updated patterns.

Quality reviews timeout with additional_review_guidance (v3.1.1)

Doctor workflow reviews that use additional_review_guidance to cross-reference prior step outputs consistently hit the 240s timeout. This is because the reviewer must read multiple files. Keep review criteria simple for intermediate steps and reserve cross-referencing reviews for final outputs only, or accept that overrides may be needed.