@gon1942/ai-dev-external-framework 0.0.0-stage → 0.8.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,40 @@
-# Temporary Holding Version
+# External AI Development Framework v0.8.1
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Single npm source tree for OpenCode / Codex / Claude Code. Installs **original upstream** Matt Pocock, Superpowers and Ponytail skills, project docs, session hooks and workflow tracking. No custom replacement Analyze/Plan/Implement/Verify/Review skills.
+
+## Publish (requires your npm account)
+
+```bash
+npm test
+npm run publish:check
+npm login
+npm publish --access public
+```
+
+Check npm package availability and account permission before publishing; this project is not published automatically.
+
+## Install from npm after publication
+
+```bash
+npx --yes @gon1942/ai-dev-external-framework@0.8.1 init my-project
+cd my-project
+opencode # or codex / claude
+```
+
+`init` creates a missing project directory, installs docs / hooks and **downloads and installs original upstream skills** in one operation. Requires Node.js >=20, Python 3, Git and internet access. A failed download is surfaced as a nonzero exit; retry is safe for unchanged files. For an existing project use `init .`; differing project-specific files are preserved, managed-file conflicts are blocked.
+
+Preview without changing files (also skips network fetch):
+
+```bash
+npx --yes @gon1942/ai-dev-external-framework@0.8.1 init my-project --dry-run
+```
+
+For offline installation of vendored **unchanged original** checkouts:
+
+```bash
+npx --yes @gon1942/ai-dev-external-framework@0.8.1 init my-project --source-dir /path/to/three-repos
+```
+
+Source directory must contain `mattpocock/`, `superpowers/`, `ponytail/`. Pin exact vendor git revisions via `--pins pins.json`. Without pins, upstream HEAD is fetched, which is not reproducible across installations. Skills are installed under `.agents/skills`, `.opencode/skills`, `.claude/skills`.
+
+`ai-dev setup`, `ai-dev install-skills`, `ai-dev status`, `ai-dev doctor`, `ai-dev work` remain available. `init` is the one-command convenience entrypoint. CRG is not installed. Actual host-specific hook, subagent and Ponytail plugin execution requires validation in each tool. The CLI does not publish to npm and does not modify user approval decisions.

package/bin/ai-dev.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+'use strict';
+const path=require('node:path');const {spawnSync}=require('node:child_process');const fs=require('node:fs');const {setup,installSkills}=require('../lib/install');
+const {init}=require('../lib/init');const {sessionStatus,formatStatus}=require('../lib/status');
+const [command,...argv]=process.argv.slice(2);const get=(k,d)=>{const i=argv.indexOf(k);return i<0?d:argv[i+1]};const has=(k)=>argv.includes(k);const project=path.resolve(get('--project',process.cwd()));
+try{
+ if(!command||['help','--help'].includes(command)){console.log(`ai-dev v0.8.1\n  init <PATH> [--agents all|opencode|codex|claude] [--dry-run] [--source-dir PATH] [--pins FILE]\n  setup [--project PATH] [--agents all|opencode|codex|claude] [--dry-run]\n  install-skills [--project PATH] [--agents all|...] [--source-dir PATH] [--dry-run] [--update] [--pins FILE]\n  status [--project PATH] [--json]\n  work <workflow.py arguments>\n  doctor [--project PATH]\n\nNote: setup installs native hooks + docs; install-skills fetches unmodified upstream skills separately.`);process.exit(0)}
+ if(command==='init'){init(argv);process.exit(0)}
+ if(!fs.existsSync(project)||!fs.statSync(project).isDirectory())throw Error('Project directory must exist: '+project);
+ if(command==='setup'){for(const action of setup(project,{dry:has('--dry-run'),agents:get('--agents','all')}))console.log(action);console.log('Native hooks may need host trust approval; see README.');}
+ else if(command==='install-skills')installSkills(project,{agents:get('--agents','all'),sourceDir:get('--source-dir',undefined),dry:has('--dry-run'),update:has('--update'),pins:get('--pins',undefined)});
+ else if(command==='status'){const s=sessionStatus(project);console.log(has('--json')?JSON.stringify(s,null,2):formatStatus(s));}
+ else if(command==='doctor'){
+  const paths=['AGENTS.md','scripts/workflow.py','.ai-dev/session-status.cjs','.claude/settings.json','.codex/hooks.json','.opencode/plugins/ai-dev-session.js'];let fail=0;
+  for(const p of paths){const good=fs.existsSync(path.join(project,p));console.log((good?'PASS ':'MISSING ')+p);if(!good)fail++}
+  for(const [name,dir] of Object.entries({codex:'.agents/skills',opencode:'.opencode/skills',claude:'.claude/skills'})){const full=path.join(project,dir);console.log((fs.existsSync(full)?'FOUND ':'NOT INSTALLED ')+`${name} upstream skills`)}
+  if(fail)process.exitCode=1;
+ }
+ else if(command==='work'){const rest=argv.filter((_,i)=>!(argv[i-1]==='--project'||argv[i]==='--project'));const r=spawnSync('python3',[path.join(project,'scripts','workflow.py'),...rest],{stdio:'inherit',cwd:project});process.exitCode=r.status??2;}
+ else throw Error('Unknown command: '+command);
+}catch(e){console.error('ERROR:',e.message);process.exitCode=2}

package/lib/init.js

@@ -0,0 +1,31 @@
+'use strict';
+const fs=require('node:fs');
+const path=require('node:path');
+const {setup,installSkills}=require('./install');
+function init(argv){
+ const value=(key)=>{const i=argv.indexOf(key);if(i<0)return undefined;if(!argv[i+1]||argv[i+1].startsWith('--'))throw Error(`Missing value for ${key}`);return argv[i+1]};
+ const positional=argv.filter((x,i)=>!x.startsWith('--')&&!['--agents','--pins','--source-dir'].includes(argv[i-1]));
+ const target=positional[0];
+ if(!target||positional.length!==1)throw Error('Usage: ai-dev init <project-directory> [--agents all] [--dry-run]');
+ const project=path.resolve(target),dry=argv.includes('--dry-run');
+ const agents=value('--agents')||'all',sourceDir=value('--source-dir'),pins=value('--pins');
+ if(!['all','opencode','codex','claude'].includes(agents))throw Error('Unknown agents option: '+agents);
+ if(fs.existsSync(project)&&!fs.statSync(project).isDirectory())throw Error('Target exists and is not a directory: '+project);
+ if(!fs.existsSync(project)){
+  console.log(`${dry?'WOULD CREATE':'CREATE'} project ${project}`);
+  if(!dry)fs.mkdirSync(project,{recursive:true});
+ }
+ // All setup actions are planned before any upstream fetch. Existing project files are never overwritten.
+ // A failed upstream fetch leaves installed docs intact, so retrying `init` is possible.
+ if(!dry||fs.existsSync(project))for(const action of setup(project,{dry,agents}))console.log(action);
+ if(dry&&!fs.existsSync(project)){
+  console.log('Dry-run: new project does not yet exist; setup and upstream skills would be installed at '+project);
+  console.log('WOULD INSTALL original upstream skills (fetch required on real install)');return;
+ }
+ if(dry){console.log('Dry-run does not download upstream repositories.');return;}
+ console.log('Installing original upstream skills...');
+ installSkills(project,{agents,sourceDir,pins});
+ console.log('INIT COMPLETE '+project);
+ console.log('Run `opencode`, `codex`, or `claude` inside the project after checking the installation.');
+}
+module.exports={init};

package/lib/install.js

@@ -0,0 +1,46 @@
+'use strict';
+const fs=require('node:fs');const path=require('node:path');const {spawnSync}=require('node:child_process');
+const ROOT=path.resolve(__dirname,'..');
+function walk(dir){const out=[];for(const e of fs.readdirSync(dir,{withFileTypes:true})){const p=path.join(dir,e.name);if(e.isDirectory())out.push(...walk(p));else out.push(p)}return out;}
+function put(file,data,dry,mode='managed'){
+ if(fs.existsSync(file)){
+  const old=fs.readFileSync(file);if(old.equals(Buffer.isBuffer(data)?data:Buffer.from(data)))return 'UNCHANGED';
+  if(mode==='managed')throw Error(`Existing file differs: ${file} (refusing overwrite)`);return 'PRESERVED';
+ }
+ if(!dry){fs.mkdirSync(path.dirname(file),{recursive:true});fs.writeFileSync(file,data)}return dry?'WOULD_CREATE':'CREATED';
+}
+function mergeHooks(file, entry, dry){let obj={};if(fs.existsSync(file)){obj=JSON.parse(fs.readFileSync(file,'utf8'));if(!obj||Array.isArray(obj)||typeof obj!=='object')throw Error(`Invalid JSON: ${file}`)}
+ obj.hooks??={};obj.hooks.SessionStart??=[];const sig=JSON.stringify(entry);if(obj.hooks.SessionStart.some(x=>JSON.stringify(x)===sig))return 'UNCHANGED';obj.hooks.SessionStart.push(entry);
+ if(!dry){fs.mkdirSync(path.dirname(file),{recursive:true});fs.writeFileSync(file,JSON.stringify(obj,null,2)+'\n')}return dry?'WOULD_MERGE':'MERGED';
+}
+function setup(project,{dry=false,agents='all'}={}){
+ const selected=agents==='all'?['opencode','codex','claude']:agents.split(',');for(const a of selected)if(!['opencode','codex','claude'].includes(a))throw Error(`Unknown agent ${a}`);
+ const actions=[];const source=path.join(ROOT,'templates');for(const f of walk(source)){
+  const rel=path.relative(source,f);if(rel==='AGENTS.md'&&fs.existsSync(path.join(project,rel))){actions.push(`PRESERVED ${rel} (manually merge the workflow guidance)`);continue}
+  const target=path.join(project,rel); actions.push(`${put(target,fs.readFileSync(f),dry,'project')} ${rel}`);
+ }
+ const py=path.join(ROOT,'scripts','workflow.py');
+ // Installed copies are self-contained and never overwritten without explicit user review.
+ actions.push(`${put(path.join(project,'scripts','workflow.py'),fs.readFileSync(py),dry)} scripts/workflow.py`);
+ const entryScript=path.join(project,'.ai-dev','session-status.cjs');
+ // The installed hook imports the exact same status engine used by `ai-dev status`.
+ const statusEngine=path.join(project,'.ai-dev','status-engine.cjs');
+ actions.push(`${put(statusEngine,fs.readFileSync(path.join(ROOT,'lib','status.js')),dry)} .ai-dev/status-engine.cjs`);
+ const portable=`const path=require('node:path');\nconst {sessionStatus,formatStatus}=require('./status-engine.cjs');\nprocess.stdout.write(formatStatus(sessionStatus(path.resolve(__dirname,'..')))+'\\n');\n`;
+ actions.push(`${put(entryScript,portable,dry)} .ai-dev/session-status.cjs`);
+ // hook command cwd is tool-defined; use absolute path resolved at setup, with robust JSON/shell quoting.
+ const cmd=`node ${JSON.stringify(entryScript)}`;
+ if(selected.includes('claude')){const target=path.join(project,'.claude','settings.json');actions.push(`${mergeHooks(target,{hooks:[{type:'command',command:cmd,timeout:15}]},dry)} .claude/settings.json (SessionStart)`)}
+ if(selected.includes('codex')){const target=path.join(project,'.codex','hooks.json');actions.push(`${mergeHooks(target,{hooks:[{type:'command',command:cmd,timeout:15}]},dry)} .codex/hooks.json (SessionStart)`)}
+ if(selected.includes('opencode')){
+  const target=path.join(project,'.opencode','plugins','ai-dev-session.js');
+  const script=`import { execFileSync } from 'node:child_process';\nexport const AiDevSession = async ({client}) => {\n const seen=new Set();\n return {event:async ({event})=>{\n  if(event.type!=='session.created')return;\n  const id=event.properties?.info?.id || event.properties?.sessionID; if(!id||seen.has(id))return;seen.add(id);\n  try{ const status=execFileSync('node',[${JSON.stringify(entryScript)}],{encoding:'utf8',timeout:15000});\n   await client.tui.showToast({body:{title:'AI work status',message:status.slice(0,900),variant:'info',duration:8000}});\n  }catch(e){console.warn('[ai-dev] session status unavailable:',String(e));}\n }};\n};\n`;
+  actions.push(`${put(target,script,dry)} .opencode/plugins/ai-dev-session.js`);
+ }
+ return actions;
+}
+function installSkills(project,options={}){
+ const args=[path.join(ROOT,'scripts','external-install.py'),'--project',project,'--agents',options.agents||'all'];if(options.sourceDir)args.push('--source-dir',options.sourceDir);if(options.dry)args.push('--dry-run');if(options.update)args.push('--update');if(options.pins)args.push('--pins',options.pins);
+ const r=spawnSync('python3',args,{stdio:'inherit'});if(r.status!==0)throw Error(`Original upstream skill install failed (exit ${r.status})`);
+}
+module.exports={setup,installSkills};

package/lib/status.js

@@ -0,0 +1,16 @@
+'use strict';
+const fs=require('node:fs'); const path=require('node:path');
+function sessionStatus(root){
+ const base=path.join(root,'docs','exec-plans','active');let items=[],warnings=[];
+ if(fs.existsSync(base))for(const ent of fs.readdirSync(base,{withFileTypes:true}).filter(x=>x.isDirectory()).sort((a,b)=>a.name.localeCompare(b.name))){
+  const file=path.join(base,ent.name,'status.json');if(!fs.existsSync(file))continue;
+  try {const s=JSON.parse(fs.readFileSync(file,'utf8')); const hasPlan=['spec.md','plan.md','ac-tests.json'].every(x=>fs.existsSync(path.join(base,ent.name,x)));let phase='PLAN_DRAFT';
+   if(s.approved===true||Boolean(s.approved_by)){phase=s.review?.verdict==='PASS'?'REVERIFY_OR_COMPLETION_CHECK':'IMPLEMENT_OR_VERIFY';}
+   else if(hasPlan){const ac=JSON.parse(fs.readFileSync(path.join(base,ent.name,'ac-tests.json'),'utf8'));if(Object.keys(ac).length)phase='PLAN_APPROVAL_REQUIRED';}
+   items.push({id:ent.name,title:s.title||'',phase,path:`docs/exec-plans/active/${ent.name}`});
+  }catch(e){warnings.push(`${ent.name}: ${e.message}`)}
+ }
+ return {project:root,active_count:items.length,tasks:items,warnings};
+}
+function formatStatus(s){const lines=['=== AI WORK SESSION STATUS ===',`Project: ${s.project}`,`Active tasks: ${s.active_count}`]; if(!s.tasks.length)lines.push('No active tasks. Do not auto-create work at session start.');for(const t of s.tasks)lines.push(`${t.id} | ${t.phase} | ${t.title}\n  ${t.path}`);for(const w of s.warnings)lines.push(`WARNING: ${w}`);lines.push('Read existing task files before starting new work. Show this summary to the user.');return lines.join('\n');}
+module.exports={sessionStatus,formatStatus};

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@gon1942/ai-dev-external-framework",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.8.1",
+  "private": false,
+  "description": "Cross-agent external skills installer, session status hooks and task tracking for OpenCode, Codex and Claude Code",
+  "bin": {
+    "ai-dev": "bin/ai-dev.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js && python3 -m unittest discover -s test -p \"test_*.py\"",
+    "prepack": "npm test",
+    "publish:check": "node scripts/publish-check.cjs && npm pack --dry-run --json"
+  },
+  "license": "MIT",
+  "files": [
+    "bin/",
+    "lib/",
+    "scripts/",
+    "templates/",
+    "adapters/",
+    "external-skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "agent-skills",
+    "opencode",
+    "codex",
+    "claude-code",
+    "workflow",
+    "task-graph"
+  ]
+}

package/scripts/external-install.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""Install unmodified upstream agent skills for Codex, OpenCode and Claude Code."""
+import argparse, json, shutil, subprocess, tempfile, pathlib, hashlib, datetime, sys
+
+ROOT=pathlib.Path(__file__).resolve().parent.parent
+CATALOG={
+'mattpocock':('https://github.com/mattpocock/skills.git', ['grill-with-docs','to-spec','to-tickets','implement','implement-spec','code-review','retro','diagnosing-bugs']),
+'superpowers':('https://github.com/obra/superpowers.git', ['brainstorming','writing-plans','test-driven-development','systematic-debugging','verification-before-completion','requesting-code-review','receiving-code-review','using-git-worktrees','subagent-driven-development']),
+'ponytail':('https://github.com/DietrichGebert/ponytail.git', ['ponytail']),
+}
+
+def run(args):
+ p=subprocess.run(args,text=True,capture_output=True)
+ if p.returncode: raise RuntimeError(f"{' '.join(args)}\n{p.stderr.strip()}")
+ return p.stdout.strip()
+
+def sha(b): return hashlib.sha256(b).hexdigest()
+
+def main():
+ ap=argparse.ArgumentParser(description=__doc__)
+ ap.add_argument('--project',required=True)
+ ap.add_argument('--agents',choices=['all','codex','opencode','claude'],default='all')
+ ap.add_argument('--source-dir',help='Optional offline folder containing mattpocock/, superpowers/ and ponytail/ checkouts')
+ ap.add_argument('--dry-run',action='store_true')
+ ap.add_argument('--pins',help='JSON mapping vendor names to exact commit SHA; required for reproducible team installs')
+ ap.add_argument('--update',action='store_true',help='Only replace files owned by a prior install when upstream changes; never overwrite foreign modifications')
+ args=ap.parse_args()
+ project=pathlib.Path(args.project).expanduser().resolve()
+ if not project.is_dir(): ap.error('project directory must exist')
+ pins=json.loads(pathlib.Path(args.pins).read_text()) if args.pins else {}
+ if pins and (set(pins)!=set(CATALOG) or any(not isinstance(v,str) or len(v)!=40 or any(c not in '0123456789abcdefABCDEF' for c in v) for v in pins.values())):
+  raise RuntimeError('pins must map every vendor to a 40-character git SHA')
+ agents=['codex','opencode','claude'] if args.agents=='all' else [args.agents]
+ # OpenCode gets its own .opencode/skills; no implicit dependency on Codex
+ dests={'codex':project/'.agents/skills','opencode':project/'.opencode/skills','claude':project/'.claude/skills'}
+ manifest_path=project/'.external-skills-lock.json'
+ old=json.loads(manifest_path.read_text()) if manifest_path.exists() else {'files':{}}
+ new={'generated_at':datetime.datetime.now(datetime.timezone.utc).isoformat(),'sources':{},'files':dict(old.get('files',{}))}
+ with tempfile.TemporaryDirectory() as td:
+  src={}
+  for vendor,(url,skills) in CATALOG.items():
+   if args.source_dir:
+    repo=pathlib.Path(args.source_dir).expanduser().resolve()/vendor
+    if not repo.is_dir(): raise RuntimeError(f'Missing offline source: {repo}')
+   else:
+    repo=pathlib.Path(td)/vendor
+    print(f'FETCH {url}',flush=True)
+    run(['git','clone',url,str(repo)]) if vendor in pins else run(['git','clone','--depth','1',url,str(repo)])
+    if vendor in pins:run(['git','-C',str(repo),'checkout','--detach',pins[vendor]])
+   src[vendor]=repo
+   try: revision=run(['git','-C',str(repo),'rev-parse','HEAD'])
+   except RuntimeError: revision='local-unversioned'
+   if vendor in pins and revision.lower()!=pins[vendor].lower():raise RuntimeError(f'Pin mismatch for {vendor}: {revision} != {pins[vendor]}')
+   new['sources'][vendor]={'url':url,'revision':revision}
+  changes=[]
+  for vendor,(_,names) in CATALOG.items():
+   repo=src[vendor]
+   for name in names:
+    matches=sorted(x for x in (repo/'skills').rglob('SKILL.md') if x.parent.name==name)
+    if len(matches)!=1:
+     raise RuntimeError(f'Missing or ambiguous REQUIRED skill {vendor}/{name}: expected 1 exact source, found {len(matches)}')
+    source=matches[0].parent
+    if not (source/'SKILL.md').is_file() or not (source/'SKILL.md').read_text(encoding='utf-8').strip():
+     raise RuntimeError(f'Empty REQUIRED skill {vendor}/{name}')
+    for agent in agents:
+     # Namespace avoids collisions; upstream SKILL.md internal name remains unmodified
+     dest=dests[agent]/name
+     if dest.exists():
+      # Compare entire directory contents before accepting or replacing
+      existing={str(x.relative_to(dest)):sha(x.read_bytes()) for x in dest.rglob('*') if x.is_file()}
+      incoming={str(x.relative_to(source)):sha(x.read_bytes()) for x in source.rglob('*') if x.is_file()}
+      if existing==incoming:
+       print(f'SKIP IDENTICAL {agent}:{name}'); continue
+      previous={k[len(str(dest.relative_to(project)))+1:]:v for k,v in old['files'].items() if k.startswith(str(dest.relative_to(project))+'/')}
+      if not(args.update and previous and previous==existing):
+       raise RuntimeError(f'Collision: {dest}. Refusing to overwrite; backup/remove manually or use --update for unchanged managed files.')
+     changes.append((source,dest,agent,vendor,name))
+  for source,dest,agent,vendor,name in changes:
+   print(f'{"WOULD INSTALL" if args.dry_run else "INSTALL"} {agent}: {vendor}/{name} -> {dest}')
+   if args.dry_run: continue
+   if dest.exists(): shutil.rmtree(dest)
+   shutil.copytree(source,dest,symlinks=False)
+  if not args.dry_run:
+   for vendor,(_,names) in CATALOG.items():
+    repo=src[vendor]
+    for name in names:
+     matches=[x for x in (repo/'skills').rglob('SKILL.md') if x.parent.name==name]
+     if len(matches)!=1: continue
+     for agent in agents:
+      dest=dests[agent]/name
+      if dest.exists():
+       for f in dest.rglob('*'):
+        if f.is_file(): new['files'][str(f.relative_to(project))]=sha(f.read_bytes())
+   manifest_path.write_text(json.dumps(new,indent=2,ensure_ascii=False)+'\n')
+  else: print('Dry-run complete: no files changed')
+ print('NOTE: This installs skill files only. Ponytail skill is installed, but its native plugin, hooks, mode-switching and other runtime capabilities are NOT installed. See README. Other upstream plugins and runtimes are not installed.')
+
+if __name__=='__main__':
+ try: main()
+ except (RuntimeError,OSError) as e:
+  print(f'ERROR: {e}',file=sys.stderr);sys.exit(2)

package/scripts/publish-check.cjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+'use strict';
+const fs=require('node:fs');const path=require('node:path');
+const pkg=require('../package.json');
+if(pkg.private===true) throw Error('package must be public');
+if(!pkg.name||!pkg.bin?.['ai-dev']||!fs.existsSync(path.join(__dirname,'..',pkg.bin['ai-dev'])))throw Error('bin missing');
+for(const p of ['scripts/external-install.py','scripts/workflow.py','templates/AGENTS.md','lib/install.js','lib/status.js'])if(!fs.existsSync(path.join(__dirname,'..',p)))throw Error('missing '+p);
+console.log('PUBLISH_CHECK_PASS',pkg.name,pkg.version);

package/scripts/verification.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+"""Declarative, project-owned verification profiles; never execute undocumented commands."""
+import argparse, json, pathlib, fnmatch, subprocess, datetime, hashlib, sys
+
+def load(project):
+    f=project/'.ai-dev/verification-profiles.json'
+    if not f.exists():raise ValueError(f'Missing verification profiles: {f}')
+    cfg=json.loads(f.read_text())
+    if not isinstance(cfg.get('profiles'),dict):raise ValueError('profiles object required')
+    for name,profile in cfg['profiles'].items():
+        if not isinstance(profile.get('patterns'),list) or not isinstance(profile.get('checks'),dict):raise ValueError('invalid profile '+name)
+        for check,cmd in profile['checks'].items():
+            if not isinstance(cmd,list) or not cmd or not all(isinstance(s,str) and s for s in cmd):raise ValueError('checks must be argv lists')
+    return cfg
+
+def decide(cfg,files):
+    found={}
+    for name,profile in cfg['profiles'].items():
+        matching=[f for f in files if any(fnmatch.fnmatch(f,pat) for pat in profile['patterns'])]
+        if matching:found[name]={'files':matching,'checks':profile['checks']}
+    return found
+
+def main():
+    ap=argparse.ArgumentParser();ap.add_argument('--project',default='.');ap.add_argument('--files',nargs='+',required=True);ap.add_argument('--run',action='store_true');args=ap.parse_args()
+    project=pathlib.Path(args.project).resolve();cfg=load(project);found=decide(cfg,args.files)
+    if not found:print(json.dumps({'profiles':{},'warning':'NO_MATCHING_PROFILE: manual verification plan required'},indent=2));return 2
+    if not args.run:print(json.dumps({'profiles':found,'note':'Preview only: choose appropriate AC mappings before execution'},indent=2));return 0
+    logs=project/'docs/generated/verification';logs.mkdir(parents=True,exist_ok=True)
+    results=[]
+    for name,data in found.items():
+        for check,cmd in data['checks'].items():
+            r=subprocess.run(cmd,cwd=project,text=True,stdout=subprocess.PIPE,stderr=subprocess.STDOUT)
+            key=datetime.datetime.now(datetime.timezone.utc).strftime('%Y%m%dT%H%M%S%fZ')
+            f=logs/(key+'-'+name+'-'+check+'.log');f.write_text(r.stdout)
+            results.append({'profile':name,'check':check,'command':cmd,'exit_code':r.returncode,'log':str(f.relative_to(project)),'sha256':hashlib.sha256(f.read_bytes()).hexdigest()})
+    print(json.dumps({'results':results},indent=2))
+    return 1 if any(x['exit_code'] for x in results) else 0
+if __name__=='__main__':
+ try:sys.exit(main())
+ except (ValueError,OSError,json.JSONDecodeError) as e:print('BLOCK:',e,file=sys.stderr);sys.exit(2)

package/scripts/workflow.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""Shared file-based gates for externally installed AI coding skills."""
+import argparse, pathlib, json, datetime, hashlib, subprocess, sys, shutil, re
+ROOT=pathlib.Path(__file__).resolve().parent.parent
+BASE=ROOT/'docs'/'exec-plans'
+def now():return datetime.datetime.now(datetime.timezone.utc).isoformat()
+def get(task):
+ if not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_-]{1,79}',task):raise ValueError('invalid task ID')
+ for state in ['active','completed']:
+  p=BASE/state/task
+  if p.is_dir():return p
+ raise ValueError(f'unknown task: {task}')
+def meta(p):return json.loads((p/'status.json').read_text())
+def save(p,data):(p/'status.json').write_text(json.dumps(data,indent=2,ensure_ascii=False)+'\n')
+def digest():
+ h=hashlib.sha256()
+ skip={'.git','.agents','.opencode','.claude','node_modules','.venv','venv','.pytest_cache','__pycache__','.external-skills-lock.json'}
+ for f in sorted(ROOT.rglob('*')):
+  if not f.is_file() or any(c in skip for c in f.relative_to(ROOT).parts):continue
+  rel=f.relative_to(ROOT).as_posix()
+  if rel.startswith('docs/exec-plans/') or rel.startswith('docs/generated/') or rel.startswith('docs/ai-workflow/') or rel.startswith('scripts/'):continue
+  h.update(rel.encode());h.update(hashlib.sha256(f.read_bytes()).digest())
+ return h.hexdigest()
+def acmap(p):
+ try:
+  data=json.loads((p/'ac-tests.json').read_text());assert isinstance(data,dict) and data
+  for k,v in data.items():assert re.fullmatch(r'AC-[0-9]+',k) and isinstance(v,list) and bool(v) and all(isinstance(x,str) and x.strip() for x in v)
+  return data
+ except (ValueError,AssertionError,OSError) as e:raise ValueError('ac-tests.json must contain AC IDs mapped to nonempty command descriptions') from e
+def proof(p):
+ records=[json.loads(line) for line in (p/'evidence.jsonl').read_text().splitlines()] if (p/'evidence.jsonl').exists() else []
+ mapping=acmap(p);d=digest();issues=[]
+ for ac in mapping:
+  if not any(x.get('ac')==ac and x.get('exit_code')==0 and x.get('source_digest')==d and x.get('log_file') and (p/x['log_file']).is_file() and x.get('command') in [v.split() for v in mapping[ac]] and not x.get('source_changed_during_test',False) for x in records):issues.append(ac+': missing current successful recorded execution')
+ return issues
+def gate(p,stage):
+ s=meta(p)
+ if stage=='implement':
+  if not (s.get('approved') is True or bool(s.get('approved_by'))):raise ValueError('plan is not human-approved')
+  if not (p/'spec.md').read_text().strip() or not (p/'plan.md').read_text().strip():raise ValueError('missing spec/plan')
+  acmap(p)
+ elif stage in ['review','complete']:
+  gate(p,'implement')
+  issues=proof(p)
+  if issues:raise ValueError('; '.join(issues))
+  if stage=='complete':
+   r=s.get('review',{})
+   if r.get('verdict')!='PASS' or r.get('source_digest')!=digest():raise ValueError('missing PASS review for current source')
+ else:raise ValueError('unknown stage')
+def main():
+ parser=argparse.ArgumentParser();sub=parser.add_subparsers(dest='cmd',required=True)
+ sub.add_parser('status');sub.add_parser('next');se=sub.add_parser('session');se.add_argument('--json',action='store_true');se.add_argument('--all',action='store_true',help='Include completed tasks (default active only)');n=sub.add_parser('new');n.add_argument('--id',required=True);n.add_argument('--title',required=True)
+ for action in ['approve','gate','run','review','complete']:
+  a=sub.add_parser(action);a.add_argument('--id',required=True)
+  if action in ['approve','complete']:a.add_argument('--user-confirmed',action='store_true',help='Agent attests explicit user approval in current conversation; not identity authentication')
+  if action=='gate':a.add_argument('--stage',choices=['implement','review','complete'],required=True)
+  if action=='run':a.add_argument('--ac',required=True);a.add_argument('command',nargs=argparse.REMAINDER)
+  if action=='review':a.add_argument('--verdict',choices=['PASS','FAIL'],required=True);a.add_argument('--notes-file',required=True)
+ args=parser.parse_args()
+ if args.cmd=='session':
+  # Read-only snapshot for a fresh agent session; do not infer approvals from chat.
+  tasks=[];problems=[]
+  states=['active','completed'] if args.all else ['active']
+  for state in states:
+   for sf in sorted((BASE/state).glob('*/status.json')):
+    q=sf.parent
+    try:
+     d=meta(q);phase='COMPLETED' if state=='completed' else 'PLAN_APPROVAL_REQUIRED';issue=''
+     if state=='active':
+      if not d.get('approved') and not d.get('approved_by'):
+       # A newly created task may have no meaningful plan yet.
+       phase='PLAN_DRAFT' if not (q/'ac-tests.json').is_file() or (q/'ac-tests.json').read_text().strip()=='{}' else 'PLAN_APPROVAL_REQUIRED'
+      else:
+       try:gate(q,'review');phase='INDEPENDENT_REVIEW_REQUIRED'
+       except (ValueError,OSError,KeyError,json.JSONDecodeError) as e:phase='IMPLEMENT_OR_VERIFY';issue=str(e)
+       if d.get('review',{}).get('verdict')=='PASS':
+        try:gate(q,'complete');phase='COMPLETION_APPROVAL_REQUIRED';issue=''
+        except (ValueError,OSError,KeyError,json.JSONDecodeError) as e:phase='REVERIFY_OR_REVIEW';issue=str(e)
+     tasks.append({'id':q.name,'title':d.get('title',''), 'phase':phase,'path':str(q.relative_to(ROOT)),'created_at':d.get('created_at',''),'issue':issue})
+    except (ValueError,OSError,KeyError,json.JSONDecodeError) as e:
+     problems.append({'path':str(q.relative_to(ROOT)),'error':str(e)})
+  order={'REVERIFY_OR_REVIEW':0,'IMPLEMENT_OR_VERIFY':1,'INDEPENDENT_REVIEW_REQUIRED':2,'PLAN_DRAFT':3,'PLAN_APPROVAL_REQUIRED':4,'COMPLETION_APPROVAL_REQUIRED':5,'COMPLETED':6}
+  tasks.sort(key=lambda d:(order.get(d['phase'],99), d['id']))
+  payload={'project':str(ROOT),'active_count':sum(t['phase']!='COMPLETED' for t in tasks),'tasks':tasks,'warnings':problems}
+  if args.json:print(json.dumps(payload,indent=2,ensure_ascii=False));return
+  print('=== AI WORK SESSION STATUS ===')
+  print('Project:',ROOT)
+  print('Active tasks:',payload['active_count'])
+  if not tasks:print('No tracked active tasks. For a new user request, create a task; do not create one merely because a session started.')
+  for t in tasks:
+   print(f"- {t['id']} | {t['phase']} | {t['title']}")
+   print('  files:',t['path'])
+   if t['issue']:print('  attention:',t['issue'])
+  for err in problems:print('WARNING:',err['path'],err['error'])
+  print('Next: Read relevant active task files; report current status before new coding. Do not infer user approval.')
+  return
+ if args.cmd=='next':
+  tasks=[]
+  for state in ['active','completed']:
+   for sf in sorted((BASE/state).glob('*/status.json')):
+    q=sf.parent;d=meta(q);phase='COMPLETED' if state=='completed' else 'PLAN_APPROVAL_REQUIRED'
+    if state=='active' and d.get('approved') is True:
+     try:gate(q,'review');phase='INDEPENDENT_REVIEW_REQUIRED'
+     except (ValueError,OSError):phase='IMPLEMENT_OR_VERIFY'
+     if d.get('review',{}).get('verdict')=='PASS':
+      try:gate(q,'complete');phase='COMPLETION_APPROVAL_REQUIRED'
+      except (ValueError,OSError):phase='REVERIFY_OR_REVIEW'
+    tasks.append({'id':q.name,'title':d.get('title'),'phase':phase,'directory':str(q.relative_to(ROOT))})
+  print(json.dumps({'tasks':tasks},indent=2,ensure_ascii=False));return
+ if args.cmd=='status':
+  for state in ['active','completed']:
+   for p in sorted((BASE/state).glob('*/status.json')):
+    d=json.loads(p.read_text());print(state,p.parent.name,d.get('title'), 'approved='+str(d.get('approved') is True or bool(d.get('approved_by'))),'review='+str(d.get('review',{}).get('verdict')))
+  return
+ if args.cmd=='new':
+  task=args.id
+  if not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_-]{1,79}',task):raise ValueError('invalid task ID')
+  if any((BASE/st/task).exists() for st in ['active','completed']):raise ValueError('task exists')
+  p=BASE/'active'/task;p.mkdir(parents=True)
+  (p/'analysis.md').write_text('# Analysis\n\n');(p/'spec.md').write_text('# Spec / Acceptance Criteria\n\n');(p/'plan.md').write_text('# Execution plan / Task graph\n\n');(p/'ac-tests.json').write_text('{}\n')
+  save(p,{'id':task,'title':args.title,'created_at':now(),'approved':False,'review':{}});print('CREATED',p);return
+ p=get(args.id);s=meta(p)
+ if args.cmd=='approve':
+  if not args.user_confirmed:raise ValueError('explicit user approval required; agent must pass --user-confirmed only after user authorizes plan')
+  if p.parent.name!='active':raise ValueError('completed task')
+  if not (p/'spec.md').read_text().strip() or not (p/'plan.md').read_text().strip():raise ValueError('missing spec/plan')
+  acmap(p)
+  adapter_file=ROOT/'.ai-dev/spec-adapter.json'
+  if adapter_file.exists():
+   adapter=json.loads(adapter_file.read_text())
+   if adapter.get('mode')=='openspec':
+    change=s.get('openspec_change_id')
+    if not change or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_.-]{0,100}',change) or not (ROOT/adapter.get('source','openspec/changes')/change).is_dir():raise ValueError('valid openspec_change_id pointing to existing change directory required')
+  s.pop('approved_by',None);s['approved']=True;s['approved_at']=now();save(p,s);print('APPROVED',p.name);return
+ if args.cmd=='gate':gate(p,args.stage);print('PASS',args.stage,p.name);return
+ if args.cmd=='run':
+  gate(p,'implement');mapping=acmap(p)
+  if args.ac not in mapping:raise ValueError('unknown AC')
+  cmd=args.command
+  if cmd and cmd[0]=='--':cmd=cmd[1:]
+  if not cmd:raise ValueError('command required after --')
+  if cmd not in [v.split() for v in mapping[args.ac]]:raise ValueError('command is not declared for this AC in ac-tests.json')
+  if cmd[0].startswith('-'):raise ValueError('command must begin with executable')
+  before=digest();proc=subprocess.run(cmd,cwd=ROOT,text=True,stdout=subprocess.PIPE,stderr=subprocess.STDOUT)
+  after=digest();logs=p/'logs';logs.mkdir(exist_ok=True)
+  tag=datetime.datetime.now(datetime.timezone.utc).strftime('%Y%m%dT%H%M%S%fZ');name='logs/'+tag+'-'+args.ac+'.log'
+  (p/name).write_text('$ '+' '.join(cmd)+'\n'+proc.stdout)
+  row={'timestamp':now(),'ac':args.ac,'command':cmd,'exit_code':proc.returncode,'source_digest':after,'source_changed_during_test':before!=after,'log_file':name}
+  if before!=after:row['exit_code']=999
+  with (p/'evidence.jsonl').open('a') as f:f.write(json.dumps(row,ensure_ascii=False)+'\n')
+  print('RECORDED',args.ac,'exit',proc.returncode,'source_changed',before!=after,'log',p/name)
+  sys.exit(1 if before!=after else proc.returncode)
+ if args.cmd=='review':
+  gate(p,'review');notes=pathlib.Path(args.notes_file).resolve()
+  if not notes.is_file() or not notes.read_text().strip():raise ValueError('review notes required')
+  reviewdir=p/'reviews';reviewdir.mkdir(exist_ok=True);dest=reviewdir/('review-'+now().replace(':','-')+'.md');shutil.copyfile(notes,dest)
+  s['review']={'verdict':args.verdict,'at':now(),'notes':str(dest.relative_to(p)),'source_digest':digest()};save(p,s);print('REVIEW',args.verdict);return
+ if args.cmd=='complete':
+  if not args.user_confirmed:raise ValueError('explicit user completion approval required; agent must pass --user-confirmed only after user authorizes completion')
+  gate(p,'complete')
+  if p.parent.name!='active':raise ValueError('already completed')
+  s.pop('completed_by',None);s['completed_at']=now();save(p,s);dst=BASE/'completed'/p.name;p.rename(dst);print('COMPLETED',dst)
+if __name__=='__main__':
+ try:main()
+ except (ValueError,OSError,json.JSONDecodeError) as e:print('BLOCK:',e,file=sys.stderr);sys.exit(2)

package/templates/.ai-dev/spec-adapter.json

@@ -0,0 +1,5 @@
+{
+  "mode": "markdown",
+  "source": "docs/product-specs",
+  "note": "Set mode=openspec and source=openspec/changes only if repository uses OpenSpec. Do not duplicate spec content."
+}

package/templates/.ai-dev/verification-profiles.json

@@ -0,0 +1,37 @@
+{
+  "profiles": {
+    "web": {
+      "patterns": [
+        "src/**/*.tsx",
+        "src/**/*.ts",
+        "web/**",
+        "src/*.ts",
+        "src/*.tsx"
+      ],
+      "checks": {
+        "lint": [
+          "npm",
+          "run",
+          "lint"
+        ],
+        "test": [
+          "npm",
+          "test"
+        ]
+      }
+    },
+    "python": {
+      "patterns": [
+        "**/*.py",
+        "*.py"
+      ],
+      "checks": {
+        "unit": [
+          "python3",
+          "-m",
+          "pytest"
+        ]
+      }
+    }
+  }
+}

package/templates/AGENTS.md

@@ -0,0 +1,23 @@
+# Shared AI development workflow — OpenCode / Codex / Claude Code
+
+**Use upstream installed skills** (Matt Pocock and Superpowers), not home-grown substitutes. CRG is independently managed. Apply this file in all three agents; actual skill discovery/activation must be verified in each host.
+
+## On every new user development request / resumed session
+1. **At the start of EVERY NEW AGENT SESSION, before planning or coding**, run `ai-dev status` from the project root. Display the active task summary to the user (ID, phase, next action), even if the user has not asked for a new task. Read applicable task files and resume rather than duplicating. This is required for OpenCode, Codex, and Claude Code. If invocation is unavailable, say the session check was not performed; never claim it ran.
+2. Read `docs/PLANS.md`, `docs/ai-workflow/POLICY.md`, and the applicable task files. Invoke upstream skills through the host's skill tool; merely reading SKILL.md is not equivalent to invoking a skill.
+3. If a new substantive request, **agent** creates task using `ai-dev work new --id TASK-... --title '...'`. Agent writes analysis.md, spec.md, plan.md, ac-tests.json using original upstream skills.
+4. Summarize plan and explicitly ask the human for approval. **Do not run approve before human approval.** An explicit natural-language approval (e.g. '계획 승인', '진행해') in response to the presented plan allows the **agent** to run `ai-dev work approve --id TASK-... --user-confirmed`. No person needs to type CLI commands.
+5. Before editing source, **agent** runs `ai-dev work gate --id TASK-... --stage implement`. Use upstream TDD/implementation skills. Never bypass a failed gate.
+6. **Agent** runs tests through `workflow.py run --id TASK-... --ac AC-.. -- <command>`, reviews real logs, and checks `workflow.py gate --id TASK-... --stage review`. Failed/insufficient coverage: fix and rerun.
+7. Invoke original `code-review` / reviewer skill in an independent context where possible, evaluate diff+spec+evidence; write substantial notes and **agent** records `workflow.py review --id TASK-... --verdict PASS|FAIL --notes-file <path>`. A recorded verdict is not proof of reviewer independence.
+8. When `workflow.py gate --id TASK-... --stage complete` passes, report `READY_FOR_REVIEW` and ask human to confirm completion. Only after explicit human confirmation may **agent** call `workflow.py complete --id TASK-... --user-confirmed`. No self-approval.
+9. For all stages, keep user interaction **natural-language only**; CLI is internal agent tooling. On session changes, any of the three agents resumes the same project files.
+
+## External skill mapping
+Analyze: `grill-with-docs`, `systematic-debugging`, CRG if installed. Plan: `to-spec`, `to-tickets`, `writing-plans`. Implement: `implement`, `test-driven-development`, optional `implement-spec` only with compatible host runtime. Verify: `verification-before-completion`. Review: `code-review`, `requesting-code-review`.
+
+## Boundaries
+No automatic commit, push, merge, or PR; never invent test/review evidence. An ambiguous 'yes' not clearly responding to a specific approval question is not consent. Agent runs no approval command on inference, and never claims person identity is verified. The CLI gates are structural; AC semantic adequacy and independent-review authenticity require critical inspection. If original skills aren't available, report that; don't claim successful invocation.
+
+## Native session status hooks
+`ai-dev setup` installs read-only SessionStart hooks (OpenCode plugin, Codex and Claude hook configs). Agents must report the injected work-state to user once per new session and read the work files before edits. Session status is a snapshot, not proof of current test evidence. Do not create a task just because a session starts.

package/templates/ARCHITECTURE.md

@@ -0,0 +1,3 @@
+# Architecture
+
+Document actual module boundaries, dependencies and important interfaces here. Keep this file project-specific.

package/templates/docs/DESIGN.md

@@ -0,0 +1,3 @@
+# Design principles
+
+Project-specific UI/UX and design constraints.

package/templates/docs/FRONTEND.md

@@ -0,0 +1,3 @@
+# Frontend conventions
+
+Document chosen frontend stack and interaction testing.

package/templates/docs/PLANS.md

@@ -0,0 +1,23 @@
+# Work tracking — CLI commands are **for agents**, not users
+
+Agents start each session with `python3 scripts/workflow.py next`, then use the **original externally installed skills**. All three hosts share `docs/exec-plans/active/TASK-ID/`.
+
+| Stage | Agent operation | Artifact / control |
+|---|---|---|
+| Analyze | `workflow.py new --id TASK-001 --title '...'` then upstream diagnostic skills | `analysis.md` |
+| Plan | upstream `to-spec`, `to-tickets`, `writing-plans` | `spec.md`, `plan.md`, `ac-tests.json` |
+| Approval | **ask user in chat**; only after explicit user plan approval: `workflow.py approve --id TASK-001 --user-confirmed` | timestamp/flag only; not user authentication |
+| Implement | `workflow.py gate --id TASK-001 --stage implement`; upstream TDD skills | code, tests, optional RED record |
+| Verify | `workflow.py run --id TASK-001 --ac AC-01 -- python3 -m pytest tests/test_feature.py` | timestamped execution log, exit code, source digest |
+| Review | `workflow.py gate --id TASK-001 --stage review`, independent original `code-review`; `workflow.py review --id TASK-001 --verdict PASS --notes-file review.md` | substantive reviewer notes; independence not automatically verified |
+| Completion | `workflow.py gate --id TASK-001 --stage complete`; **ask user in chat**; only after explicit completion approval run `workflow.py complete --id TASK-001 --user-confirmed` | moves task folder to `completed/` |
+
+Natural language interaction with user is sufficient; the agent must issue internal commands without asking user to copy commands. `--user-confirmed` is an attestation by the agent, **not** proof of human identity. Never silently auto-approve. On review FAIL, return to implementation/verification and rerun tests; a stale review cannot complete.
+
+`ac-tests.json` maps each AC ID to nonempty descriptions of test commands. Gate checks successful recorded command executions and current source digest, **not** semantic adequacy of test-to-AC mapping. Do not use a no-op or unrelated test as evidence.
+
+## New session — required first action
+
+All agents run `python3 scripts/workflow.py session` on a new session and summarize active tasks in chat **before proceeding with any work**. It is read-only: session start alone never creates, approves, reviews, or completes tasks. `--json` supports machine parsing and `--all` includes completed plans. The user does not need to type the command. Native host startup execution is not assumed: use the supplied launcher for guaranteed terminal start-time printing; host prompt compliance still needs host-level testing.
+
+When OpenSpec is active, do not duplicate its change spec under product-specs; store only task execution plan and evidence.

package/templates/docs/PRODUCT_SENSE.md

@@ -0,0 +1,3 @@
+# Product sense
+
+Define audience, user value, and non-goals.

package/templates/docs/QUALITY_SCORE.md

@@ -0,0 +1,3 @@
+# Quality criteria
+
+Document lint, typecheck, unit, integration, and E2E expectations.

package/templates/docs/RELIABILITY.md

@@ -0,0 +1,3 @@
+# Reliability
+
+Document SLAs, alerting, failure handling, backups and recovery.

package/templates/docs/SECURITY.md

@@ -0,0 +1,3 @@
+# Security
+
+Document security requirements and prohibit secrets in logs.

package/templates/docs/ai-workflow/EXTERNAL-SKILLS.md

@@ -0,0 +1,13 @@
+# Upstream skills (installed on demand)
+
+Matt Pocock: https://github.com/mattpocock/skills
+Superpowers: https://github.com/obra/superpowers
+Ponytail: https://github.com/DietrichGebert/ponytail
+
+Analyze: grill-with-docs, diagnosing-bugs, systematic-debugging, brainstorming.
+Plan: to-spec, to-tickets, writing-plans.
+Implement: implement, implement-spec, test-driven-development, using-git-worktrees, subagent-driven-development, ponytail (minimal implementation guidance).
+Verify: verification-before-completion.
+Review: code-review, requesting-code-review, receiving-code-review, retro.
+
+**Important:** Original skills can require extra capabilities/plugins/issues/subagents. Only the skill directories are installed by this package. Ponytail native plugin activation, mode switching and lifecycle hooks are NOT installed; for complete Ponytail functionality install its official host plugin following README instructions. Treat unsupported subagent and background functionality as unavailable, and use sequential fallback. CRG is intentionally not installed or modified by this package.

package/templates/docs/ai-workflow/POLICY.md

@@ -0,0 +1,8 @@
+# Governance
+- Original third-party skills are installed unmodified. External skill instructions never override repository approval rules.
+- Human approval required before implementation and completion; no autonomous commit/push/merge.
+- Verify actual exit status and retain evidence. Do not mark AC pass without a substantive coverage review.
+- Avoid sensitive data in commands and output: verification logs are stored on disk.
+- `workflow.py` is a deterministic state/file/evidence controller, not an AI skill or a substitute for actual testing.
+
+- User operates in natural language; internal CLI is agent-invoked. Explicit human approval required for plan and final completion; `--user-confirmed` is a self-attestation, not authentication.

package/templates/docs/design-docs/core-beliefs.md

@@ -0,0 +1,3 @@
+# Core beliefs
+
+Evidence precedes completion claims. Favor minimal, reversible changes.

package/templates/docs/design-docs/index.md

@@ -0,0 +1,3 @@
+# Design documentation
+
+Link architectural decisions and significant designs.

package/templates/docs/exec-plans/tech-debt-tracker.md

@@ -0,0 +1,4 @@
+# Technical debt
+
+| Item | Impact | Owner | Planned resolution |
+| --- | --- | --- | --- |

package/templates/docs/generated/db-schema.md

@@ -0,0 +1,3 @@
+# Generated schema (placeholder)
+
+No schema extracted yet.

package/templates/docs/product-specs/index.md

@@ -0,0 +1,3 @@
+# Product specifications
+
+One canonical spec lives inside each active/completed task folder; link notable specs here.

package/templates/docs/references/design-system-reference-llms.txt

@@ -0,0 +1 @@
+Placeholder: add trusted design-system reference here.

package/templates/docs/references/nixpacks-llms.txt

@@ -0,0 +1 @@
+Placeholder: add trusted Nixpacks reference here.

package/templates/docs/references/uv-llms.txt

@@ -0,0 +1 @@
+Placeholder: add trusted uv reference here.