ase: Instructions file for Codex

About

Agentic Software Engineering (ASE) is the opinionated companion tooling of Dr. Ralf S. Engelschall for combining Agentic AI Coding with Software Engineering in tools like Anthropic Claude Code CLI. ASE consists of an agent tool plugin (hooks, skills, sub-agents, meta files), a Command-Line Interface (CLI) tool, and a per-project background service bridged into the agent tool as a Model-Context-Protocol (MCP) server.

The primary target agent tool is Anthropic Claude Code CLI; GitHub Copilot CLI and OpenAI Codex CLI are secondary targets, selected via ASE_TOOL=copilot resp. ASE_TOOL=codex or the --tool CLI option.

Repository Layout

ASE ships three deliverables from one repository:

• plugin/: the agent tool plugin
  • plugin/skills/ase-xxx-xxx/: the 57 skills, each with a SKILL.md (agent instructions) and a help.md (Unix-style manual page), plus optional skill-specific files (like ase-help-intent/data.md, the concatenation of all help.md files, generated at build-time); the help.md files document only the user-facing skill surface (purpose, options, arguments, and usage examples), not the internals of the skills (the workflow steps of SKILL.md, the leveraged sub-agents, meta files, and MCP tools, and their interplay), so consult the SKILL.md and its referenced files for the latter and never add implementation details to the help.md files
  • plugin/agents/: the sub-agent definitions leveraged by the skills
  • plugin/meta/: the shared meta files, exposed to skills via ase util meta <name>: the constitution, tenets, persona, dialog, control flow, getopt, and skill output conventions (ase-{constitution,tenets,persona,dialog,control,getopt,skill}.md), the common steps shared by groups of skills (ase-common-*.md), and the artifact formats (ase-format-{meta,task,spec}.md), where the specification format ase-format-spec.md includes the SpecBook models and formats description ase-format-specbook.md and the standard SpecBook schema configuration ase-format-specbook.yaml, both generated at build-time by SpecBook (@rse/specbook)
  • plugin/hooks/: the per-agent-tool hook wiring (hooks.json, hooks-copilot.json, hooks-codex.json)
  • plugin/output-styles/: the output style ase-terse
  • plugin/mods/: the Claude Code function hooks module ("mod"), type-checked against the downloaded claude-code.d.ts: ase-mods.ts for the hooking infrastructure (the only module loaded by the engine, registering the hooks, dispatching them into the other modules, and binding the engine services for them), ase-mods-common.ts for the shared parts (styled characters, Markdown conversion, wrapping, framing, and the geometry of the band above the prompt), ase-mods-grill.ts for re-rendering the grilling tables of ASE, ase-mods-help-find.ts for the intent help (a prompt, other than a skill command, suffixed with a blank and !! matched against the help of all skills, with the proposed commands in the band above the prompt, and closed by !! again), ase-mods-help-compose.ts for the synopsis form (a skill command, bare or with its typed options and arguments, suffixed with !! composed resp. edited through a form of its SYNOPSIS in the band above the prompt, and applied by !! again), ase-mods-help-show.ts for the manual band (a skill command, bare or with its typed options and arguments, suffixed with a blank and // toggling the entire manual page of the skill in the band above the prompt, while the command is typed on, until the synopsis form opens), ase-mods-help-browse.ts for the manpage browser (a prompt of just //, or of a free text suffixed with a blank and //, browsing the manual pages of all skills, filtered by a fuzzy search initially of the free text, in the band above the prompt, with RETURN taking over the command of the selected skill), and ase-mods-help-hint.ts for the hint band (a prompt starting with a skill command showing the entire argument hint of the skill, wrapped over multiple lines, in the band above the prompt, instead of the truncated one-line argument hint of Claude Code, which is dropped for the skills)
  • plugin/.claude-plugin/, plugin/.codex-plugin/, plugin/.github/plugin/: the per-agent-tool plugin manifests
• tool/: the @rse/ase CLI
  • tool/src/ase.ts: the entry point, wiring all top-level commands
  • tool/src/ase-<command>.ts: one module per CLI command resp. command group: setup, config, service, mcp, hook, statusline, task, task-board, agent, artifact, spec, man, util, and util-{meta,diagram,worktree,mint,metric,compat}
  • tool/src/ase-lib-*.ts: the generic library modules (lib-log, lib-stdio, lib-table, lib-ignore, lib-version, lib-hash, lib-daemon-cli for the start/status/log/stop CLI commands of all background processes (servers, agents, and the agent fleet), and lib-server-cli and lib-server-bind for the CLI commands and the HTTP binding of the task store and agent relay servers)
  • tool/src/ase-setup-*.ts: the parts of ase setup (setup-common for the shared types and sub-process runner, setup-mcp for the MCP server registry, and setup-settings for the statusline and output style settings)
  • tool/src/ase-config-*.ts: the parts of ase config (config-scope for the scope chain and directory resolution, config-schema for the schema, presets, and write policies, and config-core for the layered Config class and the internal session state)
  • tool/src/ase-service-*.ts: the MCP-only tool modules of the service (service-{kv,getopt,markdown,skills,sleep,state,timestamp}) and its AI usage accounting (service-otel for the OTLP ingress, the usage windows of the task assignments, and their bookings onto the usage attachments of the tasks)
  • tool/src/ase-task-*.ts: the task functionality, where ase-task.ts itself only forwards the ase task CLI and ase_task_* MCP tools to the task store selected by project.task.store.url, through the local or remote task store clients of task-store-client (see docs/task-api.md):
    • task-format for the textual task format codec and the lifecycle models, and task-request for the codec of the agent requests attached to tasks, like the edit requests of the task boards
    • the task store: task-store-server-cli for the ase task store CLI wrapper, task-store-core for the transport-agnostic REST API functionality, task-store-server-bind for its HTTP and WebSocket binding, task-store-plugin-api for the storage plugin contract, task-store-plugin-delegate for the plugin loader and the locking storage delegate, the built-in storage plugins task-store-plugin-{ase,github,gitlab,gitea} (file-based resp. GitHub, GitLab, and Gitea Issues), and task-store-issues for the common parts of all issue tracker storage plugins
    • the task board: task-board for the ase task board CLI command, task-board-{core,graph,flow,filter,stats} for its model (where flow is the agent graph along the lifecycle model), task-board-tui (split into task-board-tui-{model,control,view,popup,style}) for the terminal UI, and task-board-web-server for the browser UI, served by the service, with its client in ase-task-board-web-client.{html,ts,vue,styl}, a Vue application bundled by Vite, whose root component is split into the modules task-board-web-client-{model,editor,control} (shared state and service access, task plan editor, and actions and key dispatching) and the components task-board-web-client-{lanes,graph,flow,agents,stats,dialog,popup,title}
  • tool/src/ase-agent-*.ts: the parts of ase agent:
    • agent-runtime for the runtime base of all agents, agent-runtime-tool for the headless agent tool invocation and the decoding of its output, agent-runtime-exec for the processes, temporary directories, jobs, and Git operations, agent-runtime-claim for the run locks and task claims of the crash recovery, agent-runtime-{phase,request} for the runtime bases of the phase resp. request agents, and agent-runtime-engine for the engine running every agent of a definition (its phase and request agents) and its facades: the built-in agents, the agents of the definition kinds, and the adhoc agent
    • agent-definition-api for the public, self-contained types of the agent definitions and their hooks (exported as the types of the @rse/ase package), agent-definition-core for the definition model (options, YAML, TypeScript, JavaScript, and built-in definition loading, discovery of the definition kinds, hooks, validation, and templates), and the directory tool/src/ase-agent-definition-builtin/ with the files {rebooter,condenser,implementer,qualifier,integrator,editor,estimator,researcher}.ts for the declarative definitions of the modes of the built-in agents
    • agent-process for the ase agent <kind> start|status|log|stop commands of a single agent, and agent-fleet for the ase agent fleet supervisor of multiple agents and the agent relay
    • the agent relay, selected by project.relay.url and passing the live presence of the agents to the task boards: agent-relay-server-cli for the ase agent relay CLI wrapper, agent-relay-core for the transport-agnostic in-memory presence, agent-relay-server-bind for its HTTP and WebSocket binding (mountable into the task store server), and agent-relay-client for the relay URL resolution, the client, and the presence reporter of the agents
  • tool/bin/ase: the published shim, loading compiled output from dst/
  • tool/man/ase{,-xxx{,-yyy}}.md: the Unix manual pages of all CLI commands (one per command and command group, where the pages of a group with third-level commands like ase task store cover them), in the remark-man Markdown format, copied at build-time into dst/man/*.md (shown by ase man); they document only the user-facing CLI surface (commands, options, arguments, configuration, and files), not the internals of tool/src/ (modules, classes, functions, types, and their interplay), so consult the source code for the latter and never add implementation details to the manual pages
  • tool/plugin/ and tool/.claude-plugin/: build-time copies of plugin/ and .claude-plugin/ -- never edit them, they are regenerated
• pages/: the GitHub Pages site (https://ase.tools), an Astro project
  • pages/src/pages/: the pages of the site (index.astro, author, design, highlights, news, project, setup, usage, workflows, typing-demo, and usecases/[usecase]), all based on pages/src/layouts/BaseLayout.astro
  • pages/src/components/*.astro: the page sections (Section-*), modals (Modal-*), widgets (Widget-*), and client-side features (Feature-*)
  • pages/src/data/*.ts: the content data, especially skills.ts (the single source of truth for skill grouping and ordering), manpages.ts (the CLI command tree, read at build-time from tool/man/*.md), news.ts (the release news, read at build-time from NEWS.md), terminology.ts (the term definitions, imported at build-time from the sibling terminology.md), and comparison.ts, fit.ts, methods.ts, nav.ts, previews.ts, site.ts, testimonials.ts, usecases.ts, and usps.ts