acek-skills 1.0.3 → 1.2.0

package/commands/sf-init.md

@@ -0,0 +1,165 @@
+---
+description: Bootstrap or refresh the project's architecture.md baseline — org aliases, tech stack, data model, integrations, and Permission Set inventory that sf-architect reads before planning any feature.
+---
+
+# /sf-init — Architecture Baseline Bootstrap
+
+This command creates (or refreshes) `architecture.md` at the project root. It is a one-time setup
+step per project — `sf-architect` reads this file on every plan afterward instead of re-scanning
+the whole project from scratch each time.
+
+**This command follows `sf-architect`'s conventions exactly:** scan before asking, never fabricate
+a name that wasn't found, every clarification is a choice with an "Other" option — never a bare
+open text prompt.
+
+---
+
+## Step 1 — Check for an existing baseline
+
+Look for `architecture.md` at the project root.
+
+- **Not found** → run the [Bootstrap Flow](#bootstrap-flow) below.
+- **Found** → run the [Refresh Flow](#refresh-flow) below. Do not blindly overwrite or blindly
+  merge — always diff and confirm first.
+
+---
+
+## Bootstrap Flow
+
+### 1. Scan the project
+
+Before asking anything, gather what can be found directly:
+
+- **Data model** — custom objects under `force-app/main/default/objects/`, their purpose (from
+  field/label context, not guessed)
+- **Components** — LWC folders and Apex classes/triggers present
+- **LWC styling convention in use** — check existing component CSS: custom `:host` brand-token
+  block (`sf-dev` standard) vs `--slds-g-*` global hooks (`shaiden` convention) vs none yet
+- **Automation layer balance** — rough split of Flow-triggered vs Apex-triggered automation found
+- **Integrations** — Named Credentials, external callouts referenced in Apex
+- **Permission Sets / Permission Set Groups** — existing inventory
+- **API version** — from `sfdx-project.json` or existing metadata
+- **Org aliases** — run `sf org list` to see what's actually configured locally
+
+### 2. Ask only what can't be scanned
+
+Batch these into one round-trip, always as choices with an "Other" option:
+
+- Which scanned org is **Production** vs **Sandbox/Dev**? (options = orgs found by `sf org list`)
+- Is there an established **data classification / retention / masking policy** already in place?
+  (options: "Yes — describe it", "No, not yet documented", "Partially — describe what exists")
+- Any **org-specific constraints** that always apply (naming conventions, governance rules,
+  deployment windows)? (options: "Yes — describe", "None beyond standard practice")
+
+If `sf org list` returns nothing or the CLI isn't available, ask for aliases directly via the
+choice format instead — never require typing from memory when a scan could have answered it.
+
+### 3. Write architecture.md
+
+Compile everything into `architecture.md` at the project root using the
+[Baseline Template](#baseline-template) below.
+
+### 4. Confirm
+
+Tell the user the file was created and that `sf-architect` will now read it automatically on
+future plans instead of re-scanning the whole project each time.
+
+---
+
+## Refresh Flow
+
+### 1. Re-scan the project
+
+Same scan as [Bootstrap Step 1](#1-scan-the-project), fresh.
+
+### 2. Diff against the existing file
+
+Compare the fresh scan to what's currently in `architecture.md`. Categorize:
+
+- **Added** — new objects/components/Permission Sets/integrations found
+- **Removed** — previously listed items no longer found
+- **Changed** — e.g. org alias no longer resolves, API version bumped
+
+Never touch manually-maintained sections (**Data Privacy Baseline** notes, **Org-Specific
+Constraints**) as part of an automatic refresh — those are only updated if the user explicitly
+asks to revise them.
+
+### 3. Present the diff and confirm before writing
+
+Show what changed as a choice question:
+
+- **Update all** — apply every detected change to the auto-scanned sections
+- **Review each change** — walk through each addition/removal one at a time for confirmation
+- **Cancel** — leave `architecture.md` untouched
+
+Do not write anything until the user picks one.
+
+### 4. Write and log
+
+Apply the confirmed changes, update the `Last Scanned` timestamp, and append one line to the
+Changelog section (e.g. `2026-07-13 — Refreshed: +2 objects, org alias updated`).
+
+---
+
+## Baseline Template
+
+```markdown
+# Architecture Baseline — [Project Name]
+
+_Generated by /sf-init — YYYY-MM-DD_
+_Last Scanned: YYYY-MM-DD HH:MM_
+
+## Org Aliases
+
+- Production: `[alias]`
+- Sandbox / Dev: `[alias]`
+
+## Tech Stack Baseline
+
+- API Version: `[version]`
+- LWC Styling Convention: [sf-dev standard SLDS 2 / shaiden / mixed — note which components use which]
+- Primary Automation Layer: [Flow-first / Apex-heavy / mixed]
+
+## Data Model Overview
+
+| Object | Type              | Purpose  |
+| ------ | ----------------- | -------- |
+| [Name] | Standard / Custom | [1 line] |
+
+## Existing Integrations
+
+| System | Type                                             | Notes    |
+| ------ | ------------------------------------------------ | -------- |
+| [Name] | Named Credential / REST callout / Platform Event | [1 line] |
+
+## Permission Set / PSG Inventory
+
+| Name   | Type                                  | Purpose  |
+| ------ | ------------------------------------- | -------- |
+| [Name] | Permission Set / Permission Set Group | [1 line] |
+
+## Data Privacy Baseline
+
+[Established classification/retention/masking policy, or "Not yet documented"]
+
+## Org-Specific Constraints
+
+[Naming conventions, governance rules, non-negotiables — manually maintained, not auto-refreshed
+by future /sf-init runs unless explicitly requested]
+
+## Changelog
+
+- YYYY-MM-DD — Initial bootstrap
+```
+
+---
+
+## Relationship to sf-architect
+
+`sf-architect`'s Discovery phase checks for this file first and reads it instead of re-scanning
+the whole project on every plan. Only feature-specific touchpoints not already covered by the
+baseline get scanned fresh. If this file doesn't exist yet when `sf-architect` runs, it falls back
+to its own full scan and may suggest running `/sf-init` first for future efficiency.
+
+Re-run `/sf-init` periodically or after major structural changes (new integration, object model
+overhaul, org alias change) — it's a refresh, not a one-time-only command.

package/package.json

@@ -1,13 +1,14 @@
 {
 	"name": "acek-skills",
-	"version": "1.0.3",
+	"version": "1.2.0",
 	"description": "Installable Claude Code skills for Salesforce development (admin, dev, BA, testing, devops, security review, data migration, ideation)",
 	"bin": {
 		"acek-skills": "bin/cli.js"
 	},
 	"files": [
 		"bin/",
-		"skills/"
+		"skills/",
+		"commands"
 	],
 	"keywords": [
 		"claude",

package/skills/sf-architect/SKILL.md

@@ -72,7 +72,7 @@ unrelated features into one plan.
 ## Workflow
 
 ```
-DISCOVERY (grill me) → DECISIONS → PLAN (gate) → EXECUTE task-by-task → RESUME (new session)
+DISCOVERY (grill me) → DECISIONS → PLAN (gate) → EXECUTE in batches (parallel where safe) → RESUME (new session)
 ```
 
 ### Phase 1 — Discovery ("Grill Me")
@@ -138,7 +138,9 @@ Nothing is built yet. This phase only produces decisions with rationale.
 
 1. Compile Discovery + Decisions into the full plan file using the [Plan Template](#plan-template).
 2. Break the work into tasks. Every task gets an ID, a description, an **Owner Skill**, a
-   dependency list, and status `P` (Pending).
+   **Touches** list (exact file(s)/component(s) it will create or modify), a dependency list, and
+   status `P` (Pending). `Touches` is what Phase 4 uses to decide which tasks are safe to run in
+   parallel — be specific and accurate here, not vague.
 3. **If any task's Owner Skill is `sf-devops` or `sf-data-migration`, resolve org aliases before
    finalizing** — see [Org Alias Resolution](#org-alias-resolution) below. Skip this step
    entirely if no task touches those two skills; don't ask about aliases a plan doesn't need.
@@ -177,18 +179,42 @@ commands.
 
 ### Phase 4 — Execute
 
-Work through tasks in dependency order, one at a time:
-
-1. Announce which task is starting and which Owner Skill's conventions apply.
-2. Set that task's status to `IP` (In Progress) in the plan file.
-3. Do the work following that owner skill's rules exactly as if that skill were invoked directly.
-4. On completion, set status to `D` (Done) and append **one line** to the Execution Log — no
-   narrative, just what changed and where.
-5. If a task cannot proceed (missing decision, blocked dependency, discovered conflict), set
-   status to `B` (Blocked), write a one-line reason, and surface it to the user immediately rather
-   than guessing.
-6. Move to the next unblocked task. If all remaining tasks are blocked, stop and ask the user how
-   to proceed — using the choice format.
+Tasks run in **batches**, not strictly one at a time. Within a batch, independent tasks are
+dispatched to parallel subagents; tasks that depend on each other still run in sequence.
+
+1. **Compute the ready set.** A task is ready when every task in its `Depends On` list is `D`.
+2. **Split the ready set into parallel-safe groups.** Two ready tasks can run in the same batch
+   only if their `Touches` values don't overlap (no shared file/component). If a task's `Touches`
+   is unclear or ambiguous, treat it as not parallel-safe — run it alone.
+3. **Dispatch the batch:**
+   - **Batch of 1** → run directly in the main thread, exactly as before (no subagent overhead
+     for solo work).
+   - **Batch of 2+** → dispatch each task to a separate subagent via the Task tool, in the same
+     turn. Each subagent prompt must state explicitly: the task description, the exact file(s) in
+     `Touches`, and "follow `sf-[owner skill]`'s conventions exactly as if that skill were invoked
+     directly" — never duplicate that skill's rules into the prompt, just name it and let it
+     trigger in the subagent's own context.
+   - **Assign each subagent in a batch a random name from the pool below, unique within that
+     batch** — used only as a tracking label in the orchestrator's own narration and Execution Log
+     ("Dispatched to Sasha"), never written into code, commits, or file content.
+4. **Only the orchestrator (main thread) writes to the plan file.** Subagents report their result
+   back; they never edit `instructions/architecture/*.md` directly. Once every subagent in the
+   batch has reported back, the orchestrator updates each task's status serially — this is what
+   prevents concurrent writes to the same plan file.
+5. **Per task, on completion:** set status to `D` (Done) and append **one line** to the Execution
+   Log — no narrative, just what changed, where, and (if dispatched in a batch) which agent name
+   handled it.
+6. **Per task, if it can't proceed** (missing decision, blocked dependency, discovered conflict):
+   set status to `B` (Blocked), write a one-line reason, and surface it to the user — a Blocked
+   task in a batch does not stop the other tasks in that same batch from completing.
+7. **Recompute and repeat.** After a batch finishes, recompute the ready set (newly-unblocked
+   tasks may now qualify) and dispatch the next batch. Continue until every task is `D`, or every
+   remaining task is `B` — in which case stop and ask the user how to proceed via the choice
+   format.
+
+**Subagent name pool** (pick unique names within a batch; reuse across different batches is fine):
+Maya, Sasha, Nadia, Kirana, Alya, Cinta, Bunga, Dewi, Farah, Gita, Intan, Laras, Mira, Nita,
+Putri, Rani, Sari, Tantri, Vina, Wulan
 
 ### Phase 5 — Resume
 
@@ -201,8 +227,12 @@ direct reference to a plan file.
    feature name and last-updated date as the option label).
 4. Read only that plan file. The **Resume Briefing** section is sufficient to continue — if it
    isn't, that's a defect in how the plan was written, not a reason to re-derive context elsewhere.
-5. Find the first task that is not `D`, confirm with the user in one line ("Resuming at TASK-04:
-   [description], owner sf-testing — proceeding"), and continue Phase 4.
+5. Find every task that is not `D`. **Any task still marked `IP` from a previous session means
+   its batch was interrupted mid-flight** — don't assume it actually finished or actually failed;
+   treat it as `P` again and re-verify its `Touches` before re-dispatching (check whether the file
+   actually reflects the change described in the task, since the interruption could have happened
+   before or after the underlying work landed). Recompute the ready/parallel-safe batch from
+   there and continue Phase 4 normally.
 
 ---
 
@@ -271,24 +301,33 @@ Permission Set Group `[PSG Name]`
 
 ## Task Breakdown
 
-| ID      | Description                                                                 | Owner Skill | Depends On | Status |
-| ------- | --------------------------------------------------------------------------- | ----------- | ---------- | ------ |
-| TASK-01 | [what]                                                                      | sf-admin    | —          | D      |
-| TASK-02 | Grant access via `[PS/PSG name from Decision 3]` — extend/create as decided | sf-admin    | TASK-01    | P      |
-| TASK-03 | [what]                                                                      | sf-dev      | TASK-01    | IP     |
-| TASK-04 | [what]                                                                      | sf-testing  | TASK-03    | P      |
-| TASK-05 | [what]                                                                      | sf-devops   | TASK-04    | P      |
+| ID      | Description                                                                 | Owner Skill | Touches                     | Depends On       | Status |
+| ------- | --------------------------------------------------------------------------- | ----------- | --------------------------- | ---------------- | ------ |
+| TASK-01 | [what]                                                                      | sf-admin    | `Project__c` (object)       | —                | D      |
+| TASK-02 | Grant access via `[PS/PSG name from Decision 3]` — extend/create as decided | sf-admin    | `[PS/PSG name]`             | TASK-01          | P      |
+| TASK-03 | [what]                                                                      | sf-dev      | `ProjectController.cls`     | TASK-01          | P      |
+| TASK-04 | [what]                                                                      | sf-dev      | `projectCard` (LWC)         | TASK-01          | P      |
+| TASK-05 | [what]                                                                      | sf-testing  | `ProjectControllerTest.cls` | TASK-03          | P      |
+| TASK-06 | [what]                                                                      | sf-devops   | manifest + deploy           | TASK-04, TASK-05 | P      |
 
 **Status codes:** `P` Pending · `IP` In Progress · `B` Blocked · `D` Done
 
+**Touches** is what makes parallel dispatch safe: TASK-02, TASK-03, and TASK-04 all depend only on
+TASK-01 and touch different things — they're a valid parallel batch. TASK-05 depends on TASK-03
+and must wait for it. TASK-06 depends on both TASK-04 and TASK-05, so it waits for the slower of
+the two.
+
 ---
 
 ## Execution Log
 
-_One line per completed or blocked task. No narrative._
+_One line per completed or blocked task. No narrative. Include the agent name if the task was
+dispatched as part of a parallel batch — omit it for solo/main-thread tasks._
 
 - YYYY-MM-DD HH:MM — TASK-01 done — Created `Project__c` fields per Decision 1
-- YYYY-MM-DD HH:MM — TASK-02 blocked — needs Decision on callout timeout, asked user
+- YYYY-MM-DD HH:MM — TASK-02 done (agent: Nadia) — Extended `Project Manager Access` PS
+- YYYY-MM-DD HH:MM — TASK-03 done (agent: Sasha) — Added `getProjects()` to `ProjectController.cls`
+- YYYY-MM-DD HH:MM — TASK-04 blocked (agent: Kirana) — needs Decision on empty-state copy, asked user
 ```
 
 ---
@@ -339,6 +378,9 @@ best if users need to review before submitting (D) Other — describe your own a
 9. **Read `architecture.md` instead of re-scanning the whole project.** If the project baseline
    exists (from `/sf-init`), it already has the tech stack, data model, Permission Set inventory,
    and org aliases — reuse it. Only scan for what's specific to the current feature.
+10. **Don't parallelize trivial batches.** A batch of 2+ is only worth subagent overhead when the
+    tasks are substantial (real file edits, not one-liners). If a "parallel-safe" batch is tiny,
+    running it directly in the main thread is often cheaper than the dispatch overhead.
 
 ---
 
@@ -356,5 +398,12 @@ best if users need to review before submitting (D) Other — describe your own a
 - ✕ Skipping the Permission Set Strategy decision because the feature "seems simple" — access
   control is part of every feature that touches an object, field, Apex class, or LWC
 - ✕ Assuming a new Permission Set is needed without first scanning for an existing one that fits
+- ✕ Dispatching two tasks in parallel when their `Touches` overlap, or when either one's
+  `Touches` is too vague to be sure it doesn't
+- ✕ Letting a subagent write directly to the plan file — only the orchestrator writes status/log
+  updates, and only after the batch reports back
+- ✕ Reusing the same agent name for two subagents within the same batch
+- ✕ Treating an `IP` task found on resume as already finished — it means the batch was
+  interrupted, not that the work landed; re-verify before re-dispatching
 - ✕ Asking the user to type an org alias from memory when `sf org list` can just be run
 - ✕ Resolving org aliases for a plan that has no `sf-devops`/`sf-data-migration` task at all