Task Artifacts

Use the global task-artifacts command, or invoke scripts/task_artifacts.py with Python 3.10 or later. The tool uses the standard library, Git, and lsof; it works with Git repositories and colocated jj repositories. It does not commit, push, run hooks, or change project configuration.

Installation and migration

For a plugin-only installation, follow the plugin tool setup in the installed plugin README. It keeps the skill in the plugin cache and creates a stable link outside skill scanning directories. Rerun this explicit setup from the new plugin root after an upgrade; it does not remove standalone skills or rewrite global rules.

For a standalone installation, keep the shared copy under ~/.agents/skills/task-artifacts. Run its installer to create the command in the current user's ~/.local/bin and relative discovery links for both Codex and Claude Code:

python3 "$HOME/.agents/skills/task-artifacts/scripts/install.py"

The installer connects ${CODEX_HOME:-$HOME/.codex}/skills/task-artifacts and ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/task-artifacts to the same shared copy. It can also be run from the earlier Codex installation: it moves that source package into the shared location and preserves the old discovery path with a relative link. Other installed skills are never replaced.

When run from a standalone distribution folder, it copies the package instead of moving it.

The standalone launcher defaults to $HOME/.agents/skills/task-artifacts; the plugin launcher defaults to $HOME/.local/share/ajigu-skills/current/skills/task-artifacts. Both honor an explicit absolute TASK_ARTIFACT_SKILL_DIR on every invocation. It does not need Codex or Claude files to run. Set TASK_ARTIFACT_SKILL_DIR consistently to an absolute path when using a different shared location; use $HOME when assigning it rather than a quoted literal ~. Relative values are rejected by both the installer and launcher.

Agent configuration overrides affect discovery links only; symbolic links at agent configuration roots are supported. Add ~/.local/bin to PATH if it is not already present. The installer does not edit shell configuration, global rule files, permissions, or hooks, and does not replace unrelated commands. --bin-dir can select another command directory already in PATH.

On another Mac, copy this shared skill and the global rule files for the agents you use (~/.codex/AGENTS.md and/or ~/.claude/CLAUDE.md). Install Python 3.10 or later and Git if missing, ensure lsof is available, then run the installer. Set CODEX_HOME or CLAUDE_CONFIG_DIR before installation for custom agent homes.

Other resources referenced by global rules must also be migrated if needed; this installer does not copy them. Start a new agent session to load its global rule changes. In Claude Code, the personal skill is also available as /task-artifacts; both agents invoke the same terminal command. No local hook or cloud-session integration is installed.

Do not migrate active task state as configuration or edit its absolute paths to make it resume. Task records contain the original repository and output locations as safety checks. A changed data directory is rejected. Archive any needed evidence, start a new task on the destination machine, and repeat its checks there.

Copying state into an identical pathname is not a machine-identity check and is unsupported. Shared caches may be rebuilt. Installation receipts are historical evidence, not runtime configuration.

Scope

Each task gets a fresh directory under ~/.local/share/task-artifacts/work/. Registration never adopts an existing build, artifacts, output, cache, or source directory. Receipts and locks are stored outside removable outputs in ~/.local/share/task-artifacts/state/.

Installing this skill does not authorize deletion. Apply cleanup only when the user has authorized removal of disposable files generated by the current task inside its registered directory. Reuse existing authorization within its stated scope; ask only when that scope is missing or unclear.

Keep running apps, deliverables, original artwork, signing files, and required evidence outside this directory. Never place the only copy of a deliverable inside it. The tool does not determine which files are valuable.

During a task

1. Run task-artifacts start --repo <repository> --label <task-label>. Keep its returned id and directory for this task only.
2. Direct disposable outputs into that directory using the project's supported output options. task-artifacts run <id> -- <command> ... sets TASK_ARTIFACT_DIR, uses the repository as its working directory, and holds a task lock. Use this entry point for commands that write or use task outputs. A new run invalidates previous verification.
3. Reuse one existing shared incremental build cache and dependency cache per project when practical. Isolate a build when concurrency or configuration requires it, and put that task-specific build under the task directory. Do not relocate global caches or change signing configuration to achieve cleanup.
4. Existing scripts do not automatically honor TASK_ARTIFACT_DIR. Pass their actual output options, use existing output environment variables, or make a task-scoped adapter in the owning project. Do not claim that fixed-path scripts have been migrated. Unregistered outputs are retained and reported.

Use an explicit source scope covering all source, configuration, test, and durable evidence changes that belong to the task. Do not include unrelated dirty files merely to get a clean workspace. Paths are literal, relative to the repository, and may refer to files or directories. A source directory also binds added and removed files under that directory.

If clean/smudge filters change file bytes, the tool may conservatively refuse a commit match; preserve outputs and inspect the mismatch.

Verification and completion

After final edits, archive the minimum useful evidence outside the task directory. Run the real required checks through verify; a no-op command is not task validation. Use actual project paths and commands in place of the variables below:

task-artifacts verify "$task_id" --source src --source tests -- ./scripts/verify.sh

The command binds successful validation to the selected files and modes, including additions and deletions. It refuses to record validation if those sources change during the checks. Source completeness and the adequacy of the checks remain the agent's responsibility.

Complete the project's authorized commit, synchronization, verification, and push workflow. Re-run validation if synchronization or later edits change the task sources. Preserve mandatory hooks and run equivalent required checks explicitly when the selected VCS does not invoke them. Do not expand the permission to commit or push merely to enable cleanup.

After a successful push, pass the actual published commit ID and branch:

task-artifacts finish "$task_id" --revision "$commit_id" --remote origin --branch "$branch"
task-artifacts finish "$task_id" --revision "$commit_id" --remote origin --branch "$branch" --apply

The first command previews eligibility. The second removes only the registered task directory. Both require the working sources and selected commit to match successful validation, a live query of the configured push destination to report that exact commit on the branch, and no managed run or detected open file in the output directory. A distinct fetch URL is not publication evidence.

Multiple push destinations are unsupported and preserve outputs. A remote query failure, newer remote tip, missing commit, changed source, or active task also preserves all outputs. Do not weaken checks to force cleanup; correct the condition or report the retained path.

If a harmless unrelated commit has advanced the branch, the exact new commit may be supplied after checking that the task sources still match.

run must cover the full lifetime of a command. Stop background workers before cleanup. An open-file check cannot prove that an unmanaged process will never access a file later; unmanaged background producers must be stopped explicitly. Cleanup is terminal for the task ID. Use a new task ID for follow-up work.

For tasks without a repository or without a published commit, do not create a repository, push, or bypass validation just to clear outputs. Report retained files instead. There is no background collector and no automatic cleanup of historical directories. Manual Git/jj pushes outside this workflow do not trigger cleanup. Global agent instructions route future coding tasks through this workflow; they are not a shell interceptor.

Validation

Run python3 scripts/test_task_artifacts.py for disposable local-repository integration tests. They do not contact production remotes or remove project files. TASK_ARTIFACT_HOME can select a separate tool data directory for testing; ordinary tasks should use the default.

The suite checks failed validation and publication, changed and uncommitted sources, concurrent use, open files, source deletion, path redirection, preview mode, and cleanup isolation.

Run python3 scripts/test_install.py to verify home relocation, custom agent homes, shared-code discovery, operation without Codex files, repeated installation, legacy symlink replacement, and preservation of unrelated skills and commands.