AgentDesk Core

+---------------------------------------------------------+
|                             _   _____            _      |
|       /\                   | | |  __ \          | |     |
|      /  \   __ _  ___ _ __ | |_| |  | | ___  ___| | __  |
|     / /\ \ / _` |/ _ \ '_ \| __| |  | |/ _ \/ __| |/ /  |
|    / ____ \ (_| |  __/ | | | |_| |__| |  __/\__ \   <   |
|   /_/    \_\__, |\___|_| |_|\__|_____/ \___||___/_|\_\  |
|             __/ |                                       |
|            |___/                                        |
|  where engineers and agents work in a shared workspace  |
+---------------------------------------------------------+

AgentDesk is a shared project notebook co-authored by developers and coding agents. Its pages are ordinary Markdown and JSON files committed to Git, so people can read the work as documentation while agents and tools can understand the same work as structured data.

There is no separate agent memory, hidden database, or UI-only state. A developer can write a requirement, an agent can turn it into a plan, and either can review or continue the other's work from the same files and history.

AgentDesk Core makes that notebook executable. It provides the conventions, schemas, templates, and headless CLI required to create, validate, index, update, search, and hand off workspace data.

One Notebook, Shared Context

Developer  <---->  Markdown + JSON in Git  <---->  Coding agent
                            |
                            +---->  AgentDesk Core
                                   templates | schemas | CLI | index

• Human-readable: requirements, plans, decisions, checklists, and references remain useful as normal project documentation.
• Machine-readable: structured front matter, task.json, and JSON Schema give agents and automation an explicit contract.
• Shared workspace: humans, agents, scripts, and optional visual clients all work with the same files.
• Continuity by default: the next developer or agent can resume from Git without reconstructing context from chat history.

Responsibilities

AgentDesk Core owns:

• Workspace conventions, task templates, and Copilot instructions
• Zod schemas, generated JSON Schema, and TypeScript types
• Front matter parsing and workspace validation
• Task hierarchy, dependency graphs, progress rollups, and scheduling rules
• Atomic writers, derived indexes, search, security scanning, and scope checks
• A headless CLI for workspace and task operations

Core computes graph data but does not render it. Browser interfaces, React components, HTTP or SSE servers, visual graph layouts, and Git review UI belong in a separate visual client.

Requirements

• Node.js 20 or later
• Git

One-Command Bootstrap

Bootstrap the current repository without installing AgentDesk globally:

npx --yes --package agentdesk-kit@latest agentdesk init --root .

npx downloads the CLI into the npm cache, runs it once, and creates the workspace configuration, JSON Schema, task templates, Copilot instructions, and tasks/ directory. The generated .github/copilot-instructions.md teaches compatible coding agents how to read and write the AgentDesk file format.

You can give a terminal-enabled coding agent this prompt:

Bootstrap this repository as an AgentDesk workspace using agentdesk-kit from
npm. Run `npx --yes --package agentdesk-kit@latest agentdesk init --root .`,
then read .github/copilot-instructions.md, create the requested task with the
AgentDesk CLI, and run `npx agentdesk validate --root .`.

For reproducible automation, replace latest with an exact version such as 0.1.0.

Installation

Global installation is optional:

npm install --global agentdesk-kit

Quick Start

Create a workspace and its first task:

agentdesk init --root ./my-workspace
agentdesk new "First task" --level epic --root ./my-workspace

Validate, format-check, and generate a Copilot handoff:

agentdesk validate --root ./my-workspace
agentdesk fmt --check --root ./my-workspace
agentdesk handoff T-0001 --root ./my-workspace

Run agentdesk help for the full command list, including indexing, task updates, context generation, archiving, scope validation, and security scans. All commands are headless and suitable for local scripts or CI.

Workspace Model

The shared notebook lives entirely in the repository:

.agentdesk/config.json         Machine-readable workspace policy
.agentdesk/jobs/               Versioned job queue and audit trail
tasks/<task-id>-<slug>/        Human- and machine-readable task notebook
templates/task/                Template used to create notebook entries

.agentdesk/index.json is derived from the source files. It can always be rebuilt and should not be edited or committed.

Public API

import {
  buildGraph,
  buildIndex,
  loadWorkspace,
  patchTask,
  renderAllSchemas,
  writeIndex,
} from "agentdesk-kit";

Consumers should import from the package root. Imports from dist/* or source paths are not part of the public contract.

Versioned Assets

The published package includes:

• templates/task/
• .github/copilot-instructions.md
• .agentdesk/schema/*.schema.json
• The renderAllSchemas() API for schemas generated from Zod

Static schemas are available through package subpaths such as agentdesk-kit/schema/task.schema.json. Breaking changes to the protocol, templates, or schemas require a major version update.

Development

npm install
npm run typecheck
npm test
npm run schema:gen -- --check
npm run build
npm pack --dry-run --ignore-scripts

Run the complete validation pipeline with:

npm run check

Releases

Release Please maintains the version, changelog, tag, and GitHub Release. Merging its release pull request publishes agentdesk-kit to npm through short-lived OIDC credentials; no npm token is stored in GitHub.

Use Conventional Commits for changes that should ship:

• fix: creates a patch release.
• feat: creates a minor release.
• feat!: or a BREAKING CHANGE: footer creates a major release.
• docs:, test:, and chore: do not trigger a release by themselves.

One-time maintainer setup

1. Commit the automation setup with a non-releasing message such as chore: configure releases, merge it to main, and wait for checks to pass.
2. If the package has never been published, bootstrap 0.1.0 once from a clean checkout of main:

npm login --auth-type=web
npm publish --access public

3. Create the matching GitHub Release and tag v0.1.0 at the published commit.
4. In the npm package settings, add a GitHub Actions trusted publisher with user Leoncl2025, repository AgentDesk, workflow release.yml, no environment, and the npm publish action enabled.
5. In GitHub Settings > Actions > General, allow GitHub Actions to create pull requests.

After one successful OIDC release, set npm publishing access to require 2FA and disallow tokens, then revoke any obsolete automation token. See CONTRIBUTING.md for the contributor workflow.

Repository Layout

src/                    Protocol, parser, graph, writers, indexer, and CLI
scripts/                Schema generation and workspace validation
templates/task/         Default task template
.agentdesk/schema/      Versioned JSON Schema files
test/                   Core behavior tests