@arjunkhera/atlas 0.3.15 → 0.3.16

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.3.15",
+  "version": "0.3.16",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, for any repository.",
   "author": {
     "name": "Arjun Khera"

package/door/cli.mjs

@@ -23,7 +23,7 @@ import { scan, toText, verdict, CHECK_VERSION, SPECS } from '../shape/check.mjs'
 import { packagePackageVersion } from './lib/releases.mjs';
 import { install, upgrade, doctor } from './lib/install.mjs';
 import { checkPaths, LIMITS } from './lib/ste.mjs';
-import { checkDesignFolder } from './lib/design.mjs';
+import { checkDesignFolder, designFolderOf, repoRootFrom } from './lib/design.mjs';
 import { writeDesignPage, readTracker } from './lib/design-build.mjs';
 import { loadPrivateTerms } from './lib/privacy.mjs';
 import { checkCommand as testsCheck, writeCommand as testsWrite } from './lib/tests.mjs';
@@ -52,6 +52,8 @@ const HELP = `atlas — the door into a repo's Atlas files
       --share                          also run the privacy filter, quotes included
       --terms <file>                   private terms; default ~/.config/atlas/private-terms.txt
   atlas design check <folder> …        check a design folder: each needed part, no state line, every code in the Key
+  atlas design folder                  print where this repo keeps its designs: design.folder in atlas.yaml, or docs/design-docs
+      --root <repo>                    the repo; default the nearest folder up from here that holds atlas.yaml
   atlas design build <folder>          build the design's page from its folder
       --tracker <file>                 the tracker data, as JSON, from the lead
       --out <file>                     the page; default docs/artifacts/<folder name>.html
@@ -117,7 +119,7 @@ export const FLAGS = Object.freeze({
   'kind-drift': { root: 'optional', 'record-kind': 'value', registry: 'value', repo: 'value' },
   check: { root: 'optional', repo: 'value', 'fail-on': 'value' },
   ste: { share: 'switch', terms: 'value' },
-  design: { tracker: 'value', out: 'value', draft: 'switch' },
+  design: { tracker: 'value', out: 'value', draft: 'switch', root: 'optional' },
   tests: { root: 'optional', halves: 'value', evidence: 'value', 'guards-from': 'value', tests: 'value', 'dry-run': 'switch', run: 'value', own: 'value', base: 'value', covers: 'switch', findings: 'value', repo: 'value', max: 'value', bot: 'value', since: 'value', out: 'value', text: 'switch', json: 'switch' },
   install: { local: 'switch', from: 'value', 'skip-global': 'switch', yes: 'switch' },
   upgrade: { version: 'optional', yes: 'switch' },
@@ -258,7 +260,14 @@ function steCommand(chosen) {
 function designCommand(chosen) {
   const what = chosen._[1];
   const folders = chosen._.slice(2);
-  if (what !== 'check' && what !== 'build') throw new Error('use atlas design check <folder> or atlas design build <folder>');
+  if (what === 'folder') {
+    if (folders.length || chosen.tracker !== undefined || chosen.out !== undefined || chosen.draft) throw new Error('atlas design folder takes only --root.');
+    const where = designFolderOf(chosen.root === undefined || chosen.root === true ? repoRootFrom(process.cwd()) : resolve(chosen.root));
+    line(where.folder);
+    return 0;
+  }
+  if (chosen.root !== undefined) throw new Error('--root works only with atlas design folder.');
+  if (what !== 'check' && what !== 'build') throw new Error('use atlas design check <folder>, atlas design build <folder> or atlas design folder');
   if (!folders.length) throw new Error(`give a design folder: atlas design ${what} <folder>`);
   if (what === 'check' && (chosen.tracker !== undefined || chosen.out !== undefined || chosen.draft)) throw new Error('--tracker, --out and --draft work only with atlas design build.');
   if (what === 'build') {

package/door/lib/design.mjs

@@ -10,7 +10,7 @@
 import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
 import { join, dirname, resolve, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { parseYaml } from '../../shape/check.mjs';
+import { parseYaml, insideRepo } from '../../shape/check.mjs';
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 export const PARTS_FILE = join(PACKAGE_ROOT, 'skills', 'sdlc-task', 'design', 'parts.yaml');
@@ -227,3 +227,52 @@ export function checkDesign(design, registry = loadRegistry()) {
 export function checkDesignFolder(folder, registry) {
   return checkDesign(readDesign(folder), registry);
 }
+
+// Where a repo keeps its designs. A repo sets the folder in atlas.yaml, as
+// `design: { folder: docs/design }`. Without the key, the folder is
+// docs/design-docs, so a repo that never sets it does not change. The shape
+// check does not read the key: a check change makes every repo's copy behind.
+// The path is relative to the repo root, plain (no `.`, `..` or `~`), and
+// never in a folder that a tool owns or a crew may not read.
+export const DEFAULT_DESIGN_FOLDER = 'docs/design-docs';
+export const CLOSED_FOLDERS = Object.freeze(['.git', '.github', '.claude', '.atlas', 'node_modules']);
+
+export function designFolderOf(root) {
+  const fallback = { folder: DEFAULT_DESIGN_FOLDER, path: join(root, DEFAULT_DESIGN_FOLDER), from: 'default' };
+  const facts = join(root, 'atlas.yaml');
+  const data = existsSync(facts) ? parseYaml(readFileSync(facts, 'utf8')) : null;
+  if (!data || typeof data !== 'object' || !Object.hasOwn(data, 'design')) return fallback;
+  const design = data.design;
+  if (!design || typeof design !== 'object' || Array.isArray(design)) throw new Error('atlas.yaml: design must be a map with one key, such as "design: { folder: docs/design }". Remove design to keep docs/design-docs.');
+  const unknown = Object.keys(design).filter((key) => key !== 'folder');
+  if (unknown.length) throw new Error(`atlas.yaml: design has the unknown key(s) ${unknown.join(', ')}. The one key is folder.`);
+  const raw = design.folder;
+  if (typeof raw !== 'string' || !raw.trim()) throw new Error('atlas.yaml: design.folder must be a path, such as docs/design.');
+  const steps = raw.trim().replace(/\/+$/, '').split('/');
+  if (raw.trim().startsWith('/') || /^[A-Za-z]:/.test(raw.trim()) || steps.some((step) => step === '' || step === '.' || step === '..' || step.includes('\\')) || steps[0].startsWith('~')) {
+    throw new Error(`atlas.yaml: design.folder "${raw}" must be a plain path inside the repo, relative to its root, such as docs/design.`);
+  }
+  if (CLOSED_FOLDERS.includes(steps[0])) throw new Error(`atlas.yaml: design.folder "${raw}" is in ${steps[0]}/, which a tool owns or a crew may not read. Pick a folder such as docs/design.`);
+  const folder = steps.join('/');
+  return { folder, path: join(root, folder), from: 'atlas.yaml' };
+}
+
+// The repo root for a command run with no --root: the nearest folder, from
+// here up, that holds atlas.yaml. The search stops at the git root. With no
+// atlas.yaml on the way, it is the folder the command ran in.
+export function repoRootFrom(start) {
+  for (let dir = resolve(start); ; dir = dirname(dir)) {
+    if (existsSync(join(dir, 'atlas.yaml'))) return dir;
+    if (existsSync(join(dir, '.git')) || dirname(dir) === dir) return resolve(start);
+  }
+}
+
+// Each design in the repo: a folder under the design folder that holds
+// design.yaml. A missing design folder holds no designs.
+export function designFoldersIn(root) {
+  const { path } = designFolderOf(root);
+  if (!existsSync(path) || !statSync(path).isDirectory()) return [];
+  return readdirSync(path, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && existsSync(join(path, entry.name, DESIGN_FILE)))
+    .map((entry) => join(path, entry.name));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.3.15",
+  "version": "0.3.16",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, as a Claude Code plugin for any repository.",
   "type": "module",
   "license": "UNLICENSED",

package/skills/lead/SKILL.md

@@ -101,7 +101,7 @@ set. A test keeps the two lists equal.
 | `atlas code-read` | To resolve the citations of a code digest |
 | `atlas ste` | Before each publish; `--share` before a page goes to anyone else |
 | `atlas tests` | `write` puts the test kit in an area. `check` runs before a merge. `proof` prints the proof table of one run |
-| `atlas design` | `check` before you show a design; `build` to make its page |
+| `atlas design` | `folder` to learn where designs live; `check` before you show a design; `build` to make its page |
 
 A person merges every file that `atlas tooling` writes.
 A person merges every file that `atlas tests write` writes.

package/skills/sdlc-task/SKILL.md

@@ -68,8 +68,9 @@ with hashes retire.)
    commit to it. Local sessions use `feature/`, `fix/` or `chore/`; cloud
    sessions use `claude/`. The pull request targets that branch.
 4. **Design** (standard and above): follow [`design/README.md`](design/README.md).
-   Pick the kinds, and say why. Make the folder `docs/design-docs/<slug>/`
-   with `design.yaml`, then write the Summary, Your words and Goals first.
+   Pick the kinds, and say why. Make the folder `<design folder>/<slug>/`
+   with `design.yaml` (`atlas design folder` prints the design folder),
+   then write the Summary, Your words and Goals first.
    Read the template for each part in `design/parts/`. List the folder in
    `docs/index.md` in the commit that first lands it. Hotfix tier skips the design: the definition of done lives on
    the work item, and a resume anchor covers pauses.
@@ -123,7 +124,7 @@ A lock is the owner's approval of a short design (target design, flow 4).
    not.
 4. Call `item_lock` with the definition of done as `scope.text`. Set
    `scope.design_doc` to a link to the design at the approved commit, such
-   as `https://github.com/<owner>/<repo>/tree/<sha>/docs/design-docs/<slug>`.
+   as `https://github.com/<owner>/<repo>/tree/<sha>/<design folder>/<slug>`.
    The verb keeps a fingerprint of that text for
    the tools. No person reads or writes a hash, and no frozen text is copied
    into the doc.

package/skills/sdlc-task/design/README.md

@@ -126,8 +126,18 @@ change as work moves went to the tracker.
 
 ## The folder
 
+Each design is one folder in the repo's design folder. `atlas design folder`
+prints that folder. A repo sets it in `atlas.yaml`:
+
+```yaml
+design:
+  folder: docs/design
+```
+
+Without the key, the design folder is `docs/design-docs`.
+
 ```text
-docs/design-docs/<slug>/
+<design folder>/<slug>/
   design.yaml      title, item, product, kinds, shared, look
   summary.md       ---
                    part: summary

package/skills/sdlc-task/templates/design-hub.html

@@ -37,7 +37,7 @@ a { color: var(--accent); }
 <div class="wrap"><table>
 <thead><tr><th>Changed</th><th>Product</th><th>Design</th><th>State</th><th>Source</th></tr></thead>
 <tbody>
-<tr><td class="when">2026-10-07</td><td class="product">atlas</td><td><a href="https://claude.ai/artifact/EXAMPLE">Design docs as walkthroughs, in one place</a></td><td><span class="state build">Building</span></td><td><a href="https://github.com/ACCOUNT/REPO/blob/master/docs/design-docs/EXAMPLE.md">design doc</a></td></tr>
+<tr><td class="when">2026-10-07</td><td class="product">atlas</td><td><a href="https://claude.ai/artifact/EXAMPLE">Design docs as walkthroughs, in one place</a></td><td><span class="state build">Building</span></td><td><a href="https://github.com/ACCOUNT/REPO/tree/master/DESIGN-FOLDER/EXAMPLE">design doc</a></td></tr>
 </tbody>
 </table></div>
 </main></body></html>