Imported from louisemalvin/agentic-workspace (AGENTS.md). Install upstream with npx skills add louisemalvin/agentic-workspace. Copyright stays with the author.

Agentic Workspace Agent Guide

Project

A small, portable context layer that turns resolved planning conversations into self-contained implementation contracts for fresh coding agents.

This repository is the source package. Consumer repositories receive project-local AGENTS.md, .tasks/, and .agents/skills/ files; they do not receive this repository's development instructions.

Stack

• Runtime: POSIX sh for core commands; Bash 3.2+ for the bundled commit skill script
• OS: Linux and macOS
• Framework: None (Shell scripts and markdown templates)
• Package manager: None

Commands

• Install: ./install.sh
• Initialize a repository: bin/agentic-workspace init [--adapters] [directory]
• Create a generic contract skeleton: bin/agent-task new "<title>"
• List task summaries: bin/agent-task list
• Test: tests/run.sh

Architecture

• .agents/skills/: canonical, interoperable project skills
• bin/agentic-workspace: safe project initialization
• bin/agent-task: optional contract-file convenience operations and the only status metadata parser
• skills/commit-changes/: user-level skill source, including the all-in-one script for committing one completed, verified implementation unit
• agents/AGENTS.md: global preferences linked into supported agent harnesses
• templates/: templates for AGENTS.md and implementation contracts
• docs/: durable format and migration documentation

Known Traps

• Path issues: always use absolute paths or resolve paths relative to repo_root when referencing files.
• Do not confuse this source repo with a consumer repository. Use bin/... while developing here; user-facing documentation uses installed command names.
• This source checkout ignores its own .tasks/ as local development artifacts. Consumer repositories do not inherit that ignore rule and may commit handoff contracts for portable execution.
• Task status comes only from YAML frontmatter. Never infer it from body text.
• Contracts are optional. Do not require one for work that does not need a planning-to-implementation handoff.
• Do not add active work state, automatic resume, planning modes, worktree management, agent coordination, or other harness orchestration.

Commits

Use Conventional Commits. During substantial implementation, finish and verify one coherent unit, then commit it before starting the next. Do not postpone all commits until the entire contract is complete, and do not create arbitrary unfinished checkpoint commits. Follow the user-level $commit-changes skill.