@alexandrealvaro/agentic 0.11.2-beta.1 → 0.11.3-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexandrealvaro/agentic",
-  "version": "0.11.2-beta.1",
+  "version": "0.11.3-beta.1",
   "description": "Bootstrap and audit AGENTS.md, ARCHITECTURE.md, ADRs, skills, and subagents for engineering production code with LLMs",
   "type": "module",
   "bin": {

package/src/commands/init.js

@@ -94,6 +94,28 @@ export const CONDITIONAL_SKILLS = [
     hintWhenAuto: 'opt-in',
     hintWhenManual: 'WORKFLOW §11 hooks scaffolder (pre-commit, pre-push)',
   },
+  // The next two skills are universal in `team` / `mature` profiles
+  // (declared in PROFILES['team' / 'mature'].universal in src/lib/profiles.js)
+  // and conditional/opt-in in `solo`. They must appear in this catalog so
+  // `availableConditionalsForProfile('solo')` lookups in `pickConditionalAuto`
+  // succeed — without these entries, `if (!def) continue` silently skipped
+  // them and a `solo` user could not opt-in to either (review B1, v0.11.3).
+  // The autoIf rule here is the universal-default; per-profile overrides
+  // come from `availableConditionalsForProfile`'s rule field.
+  {
+    name: 'agentic-architecture',
+    autoIf: () => true,
+    agents: ['claude-code', 'codex'],
+    hintWhenAuto: 'system patterns + boundaries',
+    hintWhenManual: 'opt-in (recommended once load-bearing patterns emerge)',
+  },
+  {
+    name: 'agentic-adr',
+    autoIf: () => true,
+    agents: ['claude-code', 'codex'],
+    hintWhenAuto: 'binding architectural decisions (Nygard pattern)',
+    hintWhenManual: 'opt-in (recommended for binding decisions worth recording)',
+  },
 ];
 
 const CONDITIONAL_BY_NAME = Object.fromEntries(
@@ -295,16 +317,23 @@ export async function initCommand(opts) {
       confirmReplace,
       previousStates,
       kitVersion: pkg.version,
+      profile: profileName,
     });
     allActions.push(...actions);
-    const next = nextStates[agent];
-    next.profile = profileName;
-    saveState(cwd, agent, next);
+    // installSkills now stamps `profile` into nextStates per review C3.
+    // No post-hoc injection.
+    saveState(cwd, agent, nextStates[agent]);
   }
 
+  // Dedup: agentic-architecture and agentic-adr are universal at team /
+  // mature (in REQUIRED_SKILLS) AND conditional at solo (in
+  // CONDITIONAL_SKILLS) per review B1 (v0.11.3). Without the Set, the
+  // managed-skills section would list those rows twice.
   const skillDisplayOrder = [
-    ...REQUIRED_SKILLS,
-    ...CONDITIONAL_SKILLS.map((s) => s.name),
+    ...new Set([
+      ...REQUIRED_SKILLS,
+      ...CONDITIONAL_SKILLS.map((s) => s.name),
+    ]),
   ].filter((s) => installedSkillSet.has(s));
 
   const confirmAppend = interactive

package/src/commands/profile.js

@@ -17,6 +17,10 @@ const AGENT_LABEL = {
 };
 
 function readProjectProfile(cwd) {
+  // Returns { agent: profileName }. Use `loadProjectStates(cwd)` instead
+  // when you need both the profile and the full state objects in a single
+  // pass (avoids the TOCTOU window where state files could be deleted
+  // between two reads — review C2, v0.11.3).
   const perAgent = {};
   for (const agent of VALID_AGENTS) {
     const state = loadState(cwd, agent);
@@ -25,6 +29,23 @@ function readProjectProfile(cwd) {
   return perAgent;
 }
 
+function loadProjectStates(cwd) {
+  // Single-pass load of every per-agent state file. Returns
+  // { statesByAgent, profilesByAgent }. Both objects share the same agent
+  // keys so callers can iterate one and look up the other without a
+  // second filesystem read.
+  const statesByAgent = {};
+  const profilesByAgent = {};
+  for (const agent of VALID_AGENTS) {
+    const state = loadState(cwd, agent);
+    if (state) {
+      statesByAgent[agent] = state;
+      profilesByAgent[agent] = state.profile ?? DEFAULT_PROFILE;
+    }
+  }
+  return { statesByAgent, profilesByAgent };
+}
+
 function showProfile(cwd) {
   const perAgent = readProjectProfile(cwd);
   if (Object.keys(perAgent).length === 0) {
@@ -64,8 +85,12 @@ function formatRule(rule) {
 async function setProfile(cwd, name, opts) {
   validateProfile(name);
 
-  const perAgent = readProjectProfile(cwd);
-  if (Object.keys(perAgent).length === 0) {
+  // Single load — reuse below to write. Avoids the TOCTOU window where
+  // state files could be deleted between read and re-read (review C2,
+  // v0.11.3). Previous implementation called readProjectProfile then
+  // loadState again per agent in the write loop.
+  const { statesByAgent, profilesByAgent } = loadProjectStates(cwd);
+  if (Object.keys(statesByAgent).length === 0) {
     throw new Error(
       'no agentic install detected. Run `agentic init --profile <name>` first.'
     );
@@ -73,7 +98,7 @@ async function setProfile(cwd, name, opts) {
 
   const interactive = process.stdout.isTTY && !opts.yes;
 
-  const currentProfiles = [...new Set(Object.values(perAgent))];
+  const currentProfiles = [...new Set(Object.values(profilesByAgent))];
   if (currentProfiles.length === 1 && currentProfiles[0] === name) {
     process.stdout.write(`Profile already \`${name}\` for all installed agents. No change.\n`);
     return;
@@ -82,7 +107,7 @@ async function setProfile(cwd, name, opts) {
   if (interactive) {
     p.intro(`agentic profile set ${name}`);
     p.note(
-      Object.entries(perAgent)
+      Object.entries(profilesByAgent)
         .map(([agent, profile]) => `${AGENT_LABEL[agent]}: ${profile} → ${name}`)
         .join('\n'),
       'Profile change'
@@ -101,9 +126,9 @@ async function setProfile(cwd, name, opts) {
   }
 
   // Write the new profile to each installed agent's state file before
-  // running update, so update reads the new profile.
-  for (const agent of Object.keys(perAgent)) {
-    const state = loadState(cwd, agent);
+  // running update, so update reads the new profile. Reuses the in-memory
+  // states loaded above — no second filesystem read.
+  for (const [agent, state] of Object.entries(statesByAgent)) {
     state.profile = name;
     saveState(cwd, agent, state);
   }

package/src/commands/update.js

@@ -128,18 +128,27 @@ function previouslyOptedConditional(previousStates, currentAgents, profileName)
   return [...opted];
 }
 
-function profileFromStates(previousStates, currentAgents) {
-  // If multiple agents disagree on profile, surface and bail. Profile is
-  // expected to match across agents in the same project.
+function profileFromStates(statesByAgent, currentAgents) {
+  // Profile must match across every installed agent in the project — not
+  // only across the agents the current invocation targets. Without this,
+  // `--agent claude-code` on a project where codex was installed with a
+  // different profile masks the disagreement and produces inconsistent
+  // installs. Per review B2 (v0.11.3): always inspect the FULL set of
+  // loaded states, not the narrowed slice.
   const seen = new Set();
-  for (const agent of currentAgents) {
-    const prev = previousStates[agent];
-    if (prev?.profile) seen.add(prev.profile);
+  for (const [agent, state] of Object.entries(statesByAgent)) {
+    if (state?.profile) seen.add(state.profile);
+  }
+  if (seen.size === 0) {
+    // No state on disk for any agent. Fall back to the default; current
+    // invocation is a fresh / legacy install handled by the legacy path.
+    return DEFAULT_PROFILE;
   }
-  if (seen.size === 0) return DEFAULT_PROFILE;
   if (seen.size > 1) {
     throw new Error(
-      `state files disagree on profile (${[...seen].join(', ')}). Run \`agentic profile set <name>\` to reconcile.`
+      `state files disagree on profile (${[...seen].join(
+        ', '
+      )}). Run \`agentic profile set <name>\` to reconcile across all installed agents before re-running update.`
     );
   }
   return [...seen][0];
@@ -172,7 +181,10 @@ export async function updateCommand(opts) {
     previousStates[agent] = statesByAgent[agent] ?? null;
   }
 
-  const profileName = profileFromStates(previousStates, agents);
+  // Pass the FULL loaded set, not the narrowed slice. profileFromStates
+  // surfaces cross-agent disagreement even when the current invocation
+  // targets only one agent (review B2, v0.11.3).
+  const profileName = profileFromStates(statesByAgent, agents);
   const previousOpted = previouslyOptedConditional(
     previousStates,
     agents,
@@ -269,13 +281,14 @@ export async function updateCommand(opts) {
       confirmReplace,
       previousStates: { [agent]: previousStates[agent] ?? null },
       kitVersion: pkg.version,
+      profile: profileName,
       dryRun,
       force,
     });
     allActions.push(...result.actions);
-    const next = result.nextStates[agent];
-    next.profile = profileName;
-    nextStates[agent] = next;
+    // installSkills now stamps `profile` into nextStates per review C3.
+    // No post-hoc injection.
+    nextStates[agent] = result.nextStates[agent];
   }
 
   if (!dryRun) {
@@ -284,9 +297,15 @@ export async function updateCommand(opts) {
     }
   }
 
+  // Dedup: agentic-architecture and agentic-adr are universal at team /
+  // mature (in REQUIRED_SKILLS) AND conditional at solo (in
+  // CONDITIONAL_SKILLS) per review B1 (v0.11.3). Without the Set, the
+  // managed-skills section would list those rows twice.
   const skillDisplayOrder = [
-    ...REQUIRED_SKILLS,
-    ...CONDITIONAL_SKILLS.map((s) => s.name),
+    ...new Set([
+      ...REQUIRED_SKILLS,
+      ...CONDITIONAL_SKILLS.map((s) => s.name),
+    ]),
   ].filter((s) => installedSkillSet.has(s));
 
   const confirmAppend = interactive

package/src/index.js

@@ -36,12 +36,25 @@ export async function run(argv) {
     .option('--force', 'overwrite user-edited files on conflict (non-interactive default: no)')
     .action(updateCommand);
 
+  // Profile command accepts two positionals so `agentic profile set <name>`
+  // captures the name natively. Per review C1 (v0.11.3): the prior single-
+  // positional form had Commander swallow the second arg, leaving the
+  // documented `Usage: agentic profile set <name>` error message misleading.
+  // All forms work now:
+  //   agentic profile                          → show
+  //   agentic profile show                     → show
+  //   agentic profile list                     → list
+  //   agentic profile set <name>               → set
+  //   agentic profile <name>                   → shorthand for `set <name>`
+  //   agentic profile set --name <name>        → flag form (back-compat)
   program
-    .command('profile [subcommand]')
+    .command('profile [subcommand] [name]')
     .description('Show, list, or set the project maturity profile (poc | solo | team | mature)')
-    .option('-n, --name <name>', 'profile name when used with `set` subcommand')
+    .option('-n, --name <name>', 'profile name (alternative to positional, for `set` subcommand)')
     .option('-y, --yes', 'skip confirmation prompts (non-interactive)')
-    .action(profileCommand);
+    .action((subcommand, name, opts) =>
+      profileCommand(subcommand, { ...opts, name: opts.name ?? name })
+    );
 
   await program.parseAsync(argv);
 }

package/src/lib/install.js

@@ -12,6 +12,7 @@ import {
 import { fileURLToPath } from 'node:url';
 import { basename, dirname, join, relative, sep as PATH_SEP } from 'node:path';
 import { SCHEMA_VERSION } from './state.js';
+import { DEFAULT_PROFILE, validateProfile } from './profiles.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const KIT_ROOT = join(__dirname, '..', '..');
@@ -190,9 +191,11 @@ export async function installSkills({
   confirmReplace = async () => false,
   previousStates = {},
   kitVersion = null,
+  profile = null,
   dryRun = false,
   force = false,
 }) {
+  if (profile !== null) validateProfile(profile);
   const actions = [];
   const nextStates = {};
 
@@ -302,10 +305,15 @@ export async function installSkills({
       };
     }
 
+    // Profile resolution order: explicit `profile` arg > prior state's
+    // profile > DEFAULT_PROFILE. installSkills is the single owner of the
+    // returned nextStates' shape; callers no longer inject `profile`
+    // post-hoc per review C3 (v0.11.3).
     nextStates[agent] = {
       schemaVersion: SCHEMA_VERSION,
       kitVersion: kitVersion ?? prev?.kitVersion ?? null,
       agent,
+      profile: profile ?? prev?.profile ?? DEFAULT_PROFILE,
       skills: nextSkills,
     };
   }