v1.7.0

How to install

Designed to work with any AI coding assistant that reads AGENTS.md. Built and tested on Claude Code; other assistants are untested.

Your app needs git (git init if it has none) and no uncommitted changes. You also need bash (on Windows it comes with Git for Windows) and gitleaks ≥ 8.18.0, except 8.19.0, which can't scan: use 8.19.1 or later (macOS: brew install gitleaks; Windows: winget install gitleaks).

Option 1: the skill. In your app's folder, run:

npx skills add Freakling/App-Director

That installs the app-director skill for the assistant you choose in the prompt; in Claude Code it becomes the /app-director slash command. Ask your assistant to set up App Director. The skill fetches the latest App Director release outside your app and runs onboarding. To pick up a newer release later, run the command again.

Option 2: the Claude Code plugin. In Claude Code:

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

The plugin installs the latest release. Then open a new Claude Code session in your app's folder (or run /reload-plugins), and run /app-director:app-director.

Option 3: manual install. Clone the latest release next to your app as App-Director/. The release's tag is v followed by its version number (v1.7.0 for this release), and the Releases page shows the latest one; replace <tag> in this command with it:

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.

Either way, onboarding works out whether this is a new app, an existing app or an upgrade. It installs the files and sets up the toolchain, interviews you (new app) or reads the existing code, agrees with you who owns what, and ends with one commit for you to approve. Afterwards, restart Claude Code so the new commands load.

Upgrading: run /app-director (or /app-director:app-director with the plugin), or ask your assistant to run onboarding. It detects the existing install and carries out the upgrade steps of each CHANGELOG entry newer than your version, in order.

Upgrading the plugin: run /plugin marketplace update app-director and then /plugin update app-director@app-director. Restart Claude Code, open a new session in your app's folder, and run /app-director:app-director again.

What's changed

• New: your own product brief, a template to fill in, in your own words (product/director-brief.md). Every app gets the template, whether it is new or already underway. Onboarding offers it before the interview, as an alternative to the chat interview or as an addition to it, and says why it helps: a written brief gives the assistant your intent and its context, and sets the stage for the design sessions and builds that follow. Fill it before onboarding, during it or later.
  • How it relates to the brief. product/brief.md stays the design record the assistant maintains. Your brief is input that stays as you wrote it: the assistant reads it, never edits it, and writes the current design into the brief's own sections, so each fact lives in one place.
  • Onboarding reads a filled one first. For a new app it takes the interview's answers from it and asks only what it leaves open. For an existing app it builds the initial assessment (Architecture rows, brief sections, first items) from it together with the code and the existing documents. It marks what it took (from your brief) and what it worked out itself (inferred, please confirm), records decisions with why: from your brief, and turns the undecided into open questions. Tell the assistant when the brief changes and it brings product/brief.md in line.
  • Structure. The template is the director's own: executive summary, problem statement, goals and metrics, audience, value proposition and features, user experience, technical and operations considerations, launch strategy, risks and assumptions, and open questions.
• Fix: the protected-space guard blocks absolute paths. The guard for director/ matched a file path only as written, so a write to director/ sent as an absolute path (<project>/director/x, or Windows C:\...\director\x) got through. The hook now resolves the path against the project root before matching: Windows, Git Bash and POSIX forms, .. segments and case-insensitive matching on Windows. Paths outside the project root, and folders named director elsewhere in it, are still allowed. If you rely on director/ being read-only, this closes that gap. The selftest covers each form.
  • Upgrade steps: none. The hook is framework-owned and arrives on upgrade.
• Align checks the brief against reality. align.md's item 6 is now "Brief against reality", in place of the Decisions spot-check. It reads the whole brief, checks every statement of state (a section marked later or planned, a count, a list of what exists, a line saying work waits on something, "once X exists") against the built app, the done items and the latest releases, and checks every decision line since the last docs: align commit one by one, not a sample. Mechanical drift gets fixed; design calls are reported with the stale statement named. The numbering of the other items is unchanged.
  • Upgrade steps: none. The procedure is framework-owned and arrives on upgrade.
• The README says how to update the plugin. The Install section gets an Upgrade part with the plugin update commands, as Godot-Director's and SaaSAllTheThings' READMEs have.
  • Upgrade steps: none. The README belongs to the App Director repository, not to apps.
• The README says "an agreed placeholder". Its ownership line says human-owned areas get an agreed placeholder instead of generated content.
  • Upgrade steps: none. The README belongs to the App Director repository, not to apps.
• The repository ignores OS metadata files. .gitignore keeps .DS_Store, Thumbs.db, desktop.ini and __MACOSX/ out of the repository, as the Claude plugin directory's scanner requires.
  • Upgrade steps: none. The file belongs to the App Director repository, not to apps.

Upgrade steps

1. The installer adds product/director-brief.md when the app doesn't have it (project seeds are copied once and never overwritten). After the upgrade, the assistant tells you it exists, where it is, and why writing it helps. If you fill it, the assistant reads it as ONBOARDING.md › "Your own product brief" describes and brings product/brief.md in line, marking what it inferred. Nothing else in the app changes.

The other changes need no steps: the protected-space hook, the align procedure and the framework's own files arrive on upgrade.