v1.6.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: 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: npx 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: 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 clone. Clone the latest release next to your app as App-Director/. The release's tag is v followed by its version number, 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.

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.

What's changed

• New: /research, the research assistant (.app-director/procedures/research.md). When a design question depends on facts nobody has checked, or you ask for research, a read-only researcher subagent looks into it in a fresh context and reports a note. It informs; you decide: its recommendation is one option shown with its reason, and it never records a decision, edits the brief or product/decisions.md, answers an Open Question, or asks you anything. It states its assumptions in the note instead.
  • Research is a task type. Research items get their own IDs, R<n>, drawn from the Next IDs line like bugs. Instead of Done when they have Question: and, when they feed an open question, Informs: Q<n>. They are sized like any item, and the size picks the model. An item is done when its note exists.
  • Two ways to start. On the fly: a design session delegates a complex question, or you run /research <question>, and the item is created and run at once. For later: queue the item, and list it under Depends on of the tasks that need its findings. A task that needs the decision stays gated by the open question itself.
  • The note. One dated file per topic in product/research/, written by the orchestrator (the researcher writes no file): conclusion first, then options, a recommendation, sources with a tier and a confidence, and the date the claims were verified. A design session lists the notes on its topic before presenting options, and a decision that followed research ends its product/decisions.md line with the note's path.
  • research-domain.md adds what the researcher needs for apps: stacks and libraries (how a library is judged), licences, and app-store and platform requirements.
  • /next-task hands research items to the researcher instead of the builder. Research changes no code, so no check runs and no review follows; the note and the records are committed together. A run goes on after a research item and lists the questions now ready for a design call.
  • /align checks the R counter, the fields of research items, and that every done research item has a note.
  • Web access applies to every session. settings.json now allows WebSearch and WebFetch. Claude Code can't scope a permission to one subagent, so the allow covers every session in the app, not only the researcher; the researcher's own tool list (Read, Grep, Glob, WebSearch, WebFetch) is what keeps it read-only. The evidence rules keep confidential project text out of public search queries. To keep them asking, add both to the ask list in .claude/settings.local.json.
  • product/research/README.md seeds the note folder. The README, ONBOARDING.md, the example and the behaviour scenarios list the command, and selftest.sh checks that the files exist, that the researcher has only its read, search and fetch tools, that settings allow web search and fetch, that the procedures are wired to it, and that a commit with only a note skips the project check.

Upgrade steps

1. In TASKS.md, add an R counter to the Next IDs line: **Next IDs:** T<n> · B<n> · R1.
2. Create product/research/ with the seed README.md (the installer copies it when missing).
3. Restart Claude Code so the /research skill, the researcher agent and the changed settings.json load.

WebSearch and WebFetch are allowed for every session in the app, not only for the researcher. If you want Claude Code to ask before each use, add both to the ask list in .claude/settings.local.json.