Skip to content

App-Director

Small web, mobile and desktop apps

Make the app you designed, with AI doing the building and you staying the director. App-Director works for new apps and apps already in development, on TypeScript, Flutter or Python. You decide what the app does, how it should feel and what gets built next; the AI builds, tests and keeps the records.

Repository README Procedures

What the check enforces

bash tools/check.sh runs four steps:

  1. UI purity: fails when a file in a UI folder imports from a data-layer folder. Screens display state and call services; they never fetch data or call storage directly.
  2. Secrets: runs gitleaks on the working tree and fails when a credential is found. The pre-commit hook also scans staged changes, so secrets are caught before they enter git history.
  3. Stack: the type check, lint and tests for the app's stack (tools/stacks/typescript.sh, flutter.sh or python.sh).
  4. Custom: runs tools/check.local.sh, if the app has one.

The UI and data folders are set in tools/check.cfg. If gitleaks is missing, too old or can't scan, the check exits 3 and never passes silently.

Install

You need git with no uncommitted changes, bash (on Windows it comes with Git for Windows) and gitleaks 8.18.0 or newer, except 8.19.0, which can't scan. Every option installs the latest release, tagged v followed by its version, not main.

In the app's folder:

npx skills add Freakling/App-Director

In Claude Code it becomes the /app-director command. The skill fetches the latest release outside your app and runs onboarding.

/plugin marketplace add Freakling/App-Director
/plugin install app-director@app-director

Then open a new session in the app's folder and run /app-director:app-director.

Clone the latest release next to your app as App-Director/, using the release's tag from the Releases page:

git clone --branch <tag> --depth 1 https://github.com/Freakling/App-Director.git App-Director

Then ask your assistant:

Read App-Director/ONBOARDING.md and follow it to install App Director into this project.

Onboarding works out whether this is a new app, an existing app or an upgrade, sets up the toolchain, interviews you or reads the code (and offers a product brief template, product/director-brief.md, to fill in first, in your own words, which gives the agent your intent and context for the sessions and builds that follow), agrees who owns what, and ends with one commit for you to approve. Restart Claude Code afterwards so the commands load. Each new clone later needs bash tools/setup-clone.sh. Step by step, with what onboarding asks: where do I start with an app?, or I already have a project for an existing app.

Commands

Command What it does
/next-task Builds the next ready item in a fresh context, proves it with the check, updates the records and commits. Step by step: how do I get things built?
/design A design session on a topic, or /design questions to rank the open questions by what they unblock. Step by step: how do I decide what gets built?
/research A read-only researcher answers one question in a fresh context and writes a dated note with its sources to product/research/. It informs; you decide. Procedure: research.md. Step by step: I need facts before I decide
/acceptance Prepares or processes a checklist of built behaviour for you to tick Works or Broken. Step by step: how do I check that what was built works?
/align Consistency pass across the brief, decisions, tasks, AGENTS.md and check config. Step by step: the records and the code don't agree
/drift-reset Design drift reset, started only by you; /drift-reset postmortem after the rebuild. Step by step: the system was not built as I intended
/prune Moves done items to TASKS-archive.md. Step by step: the task list is getting long
/release Runs the check, builds for the target platform and walks you through the deploy. Shared behaviour and this repo's section: /release. Step by step: how do I ship it?
/refresh-model-sizing Sets or updates the model for each task size. Step by step: it's costing more than I'd like

Read more

Logic lives in the logic layer, not the UI.Freakling/App-Director