siesa-agents 2.1.68 → 2.1.70

package/claude/commands/jira_sync/sync-epics-stories.md

@@ -0,0 +1,5 @@
+---
+description: 'Sync Epics and Stories'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @_siesa-agents/sa/sync-epics-stories/workflow.md, READ its entire contents and follow its directions exactly!

package/claude/commands/sa-jira-sync.md

@@ -0,0 +1,11 @@
+---
+name: sa-jira-sync
+description: Query Jira and return a minimal hierarchy of Epics → Stories → Subtasks for a given project and epic status. Returns only id, key, name, and status for each level. Use when the user needs to inspect or export the epic/story/subtask structure from siesa-team or siesa-test-sandbox.
+argument-hint: [PROJECT-KEY] [--status "Epic Status"]
+user-invocable: true
+allowed-tools: Bash, Read, Write
+---
+
+Handle the Jira sync request: **$ARGUMENTS**
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @_siesa-agents/sa/sa-jira-sync-api/jira-sync-api.md, READ its entire contents and follow its directions exactly!

package/gemini/commands/bmad-workflow-bmm-code-review.toml

@@ -3,10 +3,11 @@ prompt = """
 IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
 
 <steps CRITICAL="TRUE">
-1. Always LOAD the FULL @_bmad/core/tasks/workflow.xml
-2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @_bmad/bmm/workflows/4-implementation/code-review/workflow.yaml
-3. Pass the yaml path _bmad/bmm/workflows/4-implementation/code-review/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
-4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
-5. Save outputs after EACH section when generating any documents from templates
+1. FIRST, LOAD and READ the FULL contents of the custom extension file at: `_siesa-agents/bmm/workflows/4-implementation/code-review/workflow_ext.md`. You MUST assimilate these pre-requisites before doing anything else.
+2. Always LOAD the FULL @_bmad/core/tasks/workflow.xml
+3. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @_bmad/bmm/workflows/4-implementation/code-review/workflow.yaml
+4. Pass the yaml path _bmad/bmm/workflows/4-implementation/code-review/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+5. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+6. Save outputs after EACH section when generating any documents from templates
 </steps>
 """

package/gemini/commands/sa-jira-sync.toml

@@ -0,0 +1,9 @@
+description = "SA: Query Jira and return a minimal hierarchy of Epics → Stories → Subtasks for a given project and epic status. Returns only id, key, name, and status for each level."
+prompt = """
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @_siesa-agents/sa/sa-jira-sync-api/jira-sync-api.md, READ its entire contents and follow its directions exactly!
+
+Parse the user arguments: **$ARGUMENTS**
+- First positional arg → PROJECT_KEY (e.g. PPS)
+- --status "..." → filter epics by this status name (default: En curso)
+- If no PROJECT_KEY is provided, prompt the user for one.
+"""

package/gemini/commands/sa-workflow-sync-epics-stories.toml

@@ -0,0 +1,4 @@
+description = "SA Workflow: sync-epics-stories — Sync Epics and Stories with Jira"
+prompt = """
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @_siesa-agents/sa/sync-epics-stories/workflow.md, READ its entire contents and follow its directions exactly!
+"""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "siesa-agents",
-  "version": "2.1.68",
+  "version": "2.1.70",
   "description": "Paquete para instalar y configurar agentes SIESA en tu proyecto",
   "main": "index.js",
   "bin": {

package/siesa-agents/bmm/workflows/2-plan-workflows/prd/workflow_ext.md

@@ -16,11 +16,30 @@ Cuando el workflow llegue a la fase de descubrimiento, presentar al usuario este
 > **2. Proporcionarlos manualmente** — Puedes pegarlos aquí, compartir un archivo `.txt` o `.md`, o describirlos en texto libre."
 
 <!-- INSTRUCCIONES DE WORKFLOW — NO mostrar al usuario -->
-- Si el usuario elige **opción 1 (Jira):** Invocar el skill `get-features` (UBICADO EN .claude\commands\get-features\SKILL.md) usando el Skill tool con `skill: "get-features"`. El skill se encargará de autenticarse con Jira, seleccionar instancia y proyecto, y generar el árbol de features en `_bmad-output/planning-artifacts/jira-trees/`. Una vez generado, leer ese archivo y extraer la lista de features del resultado para usarla como estructura del PRD.
-- Si el usuario elige **opción 2 (Manual):** Aceptar la lista de features que el usuario proporcione en cualquier formato (texto libre, `.txt`, `.md` o copia-pegado) y procesarla directamente.
+- Si el usuario elige **opción 1 (Jira):** Invocar el skill `get-features` (UBICADO EN .claude\commands\get-features\SKILL.md) usando el Skill tool con `skill: "get-features"`. El skill se encargará de autenticarse con Jira, seleccionar instancia y proyecto, y generar el árbol de features en `_bmad-output/planning-artifacts/jira-trees/`. Una vez generado, leer ese archivo y extraer la lista de features del resultado para usarla como estructura del PRD. Por cada feature extraído de Jira, **incluir obligatoriamente** el marcador `FEATURE_CODE_JIRA={ISSUE_KEY}` en su sección del PRD (donde `{ISSUE_KEY}` es el ID del issue en Jira, ej: `PROY-123`). Este marcador es crítico para la sincronización posterior con Jira:
+  - Los shards del PRD (`prd/f{N}-*.md`) y los shards de épicas (`epics/f{N}-*.md`) deben contener este marcador.
+  - Al sincronizar, el workflow resuelve el ID con este orden de prioridad: (1) busca `FEATURE_CODE_JIRA=` en el shard de la épica; (2) si no lo encuentra, lo busca en el shard del PRD correspondiente.
+  - ⚠️ Si ninguno de los dos shards contiene el marcador, la sincronización fallará para ese feature. Es responsabilidad del ingeniero asegurar que el marcador exista en al menos uno de los dos shards antes de ejecutar la sincronización.
+- Si el usuario elige **opción 2 (Manual):** Aceptar la lista de features que el usuario proporcione en cualquier formato (texto libre, `.txt`, `.md` o copia-pegado) y procesarla directamente. Por cada feature creado manualmente, incluir el marcador `FEATURE_CODE_JIRA=PENDING:{feature-slug}` (donde `{feature-slug}` es el nombre del feature en kebab-case, ej: `FEATURE_CODE_JIRA=PENDING:gestion-de-clientes`). Este valor temporal indica que el feature aún no existe en Jira y será creado automáticamente cuando el ingeniero ejecute `jira_sync`.
 
 Inyectar los features confirmados como estructura del PRD: cada feature debe quedar como una sección `### feature — {Name}` dentro del documento.
 
+<!-- INSTRUCCIONES DE WORKFLOW — NO mostrar al usuario -->
+**Si el PRD ya fue shardeado (existe la carpeta `prd/` con archivos `f{N}-*.md`):**
+- **NO modificar** el PRD maestro original.
+- Por cada nuevo feature que el ingeniero quiera agregar, ejecutar el siguiente flujo de resolución **antes de crear el shard**:
+
+  1. Invocar el skill `get-features` (usando el Skill tool con `skill: "get-features"`) para traer el árbol actualizado de features desde Jira.
+  2. Leer el árbol generado en `_bmad-output/planning-artifacts/jira-trees/` y filtrar los features que **no tienen shard local** (cuyo `ISSUE_KEY` no aparece en ningún `prd/f{N}-*.md` existente).
+  3. Mostrar al ingeniero la lista filtrada y preguntar:
+     > *"Se encontraron los siguientes features en Jira sin shard local. ¿Alguno corresponde al feature que acabas de describir?"*
+     - Listar cada feature con su KEY y nombre (ej: `PROY-89 — Gestión de Clientes`).
+     - Incluir siempre la opción: **"Ninguno — es un feature completamente nuevo, no existe en Jira"**.
+  4. **Si el ingeniero selecciona un feature de Jira** → crear el shard `f{N}-{feature-name}.md` con `FEATURE_CODE_JIRA={ISSUE_KEY}` del feature seleccionado.
+  5. **Si el ingeniero elige "Ninguno"** → crear el shard `f{N}-{feature-name}.md` con `FEATURE_CODE_JIRA=PENDING:{feature-slug}`.
+
+- Informar al ingeniero qué archivo shard fue creado y que puede enriquecerlo con detalle adicional de forma independiente.
+
 ## 2. Naturaleza del PRD Generado
 
 El PRD que produce este workflow es un **documento maestro general**. Contiene la definición base de cada feature a nivel de alcance, objetivos y requisitos generales — NO el detalle profundo de implementación de cada uno.

package/siesa-agents/bmm/workflows/3-solutioning/create-epics-and-stories/workflow_ext.md

@@ -63,5 +63,11 @@ Una vez confirmada la lista de features, inyectar las siguientes reglas de estru
 
 6. **Step 3 (Stories)**: Al generar épicas y stories, escribir cada feature como sección `##`, con sus épicas como `###` y stories como `####`. La numeración de stories sigue el patrón `{epic_num}.{story_num}` (ej: Story 3.1, Story 3.2 para Epic 3).
 
+7. **Marcador `FEATURE_CODE_JIRA`**: Cada archivo shard de épica debe comenzar con la siguiente línea como **primera línea del archivo**, antes de cualquier heading:
+   ```
+   <!-- FEATURE_CODE_JIRA=PENDING:{slug} -->
+   ```
+   donde `{slug}` es el mismo slug kebab-case del feature correspondiente en el PRD shard (ej: `gestion-de-clientes`, `asociacion-cliente-contacto`). Este marcador es requerido por el workflow `sync-epics-stories` para asociar el shard con su issue en Jira.
+
 **PASO 3: CONTINUAR CON WORKFLOW ESTÁNDAR**
 Después de inyectar el contexto, continuar con el flujo normal del workflow `create-epics-and-stories` (step-01 → step-02 → step-03 → step-04), aplicando las reglas de estructura en cada paso.

package/siesa-agents/bmm/workflows/4-implementation/code-review/workflow_ext.md

@@ -20,3 +20,122 @@ The following rules must be kept in memory and applied at the appropriate moment
    - Compile a list of **Actual Changed Files**
 3. If no:
    - Note that review will rely solely on Story's File List (Warning)
+
+## 2. Sub-agents: only when invoked via quick-dev
+
+Sub-agents **must NOT be used** when the code review workflow is invoked directly (e.g., `/code-review`). Sub-agents are only permitted when the workflow is triggered as part of **quick-dev** (e.g., `/quick-dev`).
+
+- If invoked directly → follow the standard sequential workflow steps without spawning any sub-agents.
+- If invoked from quick-dev → sub-agents may be used as defined by the quick-dev orchestration.
+---
+
+## 3. During step-06-jira-sync: REPLACE entirely with Automated sa-jira-sync-api
+
+**TRIGGER CONDITION:** This override applies ONLY when `{{new_status}} == 'done'` (as determined in step-05-sync-sprint).
+
+**BEHAVIOR:** Completely replace the base step-06 MCP-based logic with an automated, silent execution using the sa-jira-sync-api infrastructure (Node.js direct API). The user must NOT be shown any menus or prompts — display only brief status lines.
+
+### Infrastructure References
+
+- OAuth tokens: `{project-root}/.claude/commands/get-features/tokens.json`
+- OAuth config: `{project-root}/.claude/commands/get-features/oauth-config.json`
+- Jira config: `{project-root}/_bmad-output/jira_docs/project_config.yaml`
+- Story sync step: `{project-root}/_siesa-agents/sa/sync-epics-stories/steps/step-05-stories.md`
+- Story template: `{project-root}/_siesa-agents/sa/sync-epics-stories/data/templates/story-template.json`
+- Task template: `{project-root}/_siesa-agents/sa/sync-epics-stories/data/templates/task-template.json`
+- Subtask template: `{project-root}/_siesa-agents/sa/sync-epics-stories/data/templates/subtask-template.json`
+
+### Automated Execution Sequence
+
+#### A. Guard Check
+
+If `{{new_status}} != 'done'`:
+- Output: `ℹ️ Story status is '{{new_status}}'. Skipping Jira sync.`
+- Immediately proceed to step-07 without any further action.
+
+#### B. Load Jira Configuration (Silent)
+
+1. Check if `{project-root}/_bmad-output/jira_docs/project_config.yaml` exists.
+   - If NOT exists: Output `⚠️ No Jira config found (project_config.yaml). Skipping Jira sync.` then proceed to step-07.
+   - If exists: Read and extract `project_key`, `cloud_id`, `jira_url`.
+
+2. Refresh OAuth access token using inline Node.js:
+   - Read `tokens.json` → extract `refresh_token`
+   - Read `oauth-config.json` → extract `client_id`, `client_secret`
+   - `POST https://auth.atlassian.com/oauth/token` with `grant_type: refresh_token`
+   - Save new `access_token` (and `refresh_token` if returned) back to `tokens.json`
+   - If refresh fails: Output `⚠️ OAuth token refresh failed. Skipping Jira sync.` then proceed to step-07.
+
+Output: `🔄 Syncing story with Jira...`
+
+#### C. Pre-configure Scope for This Story (Silent)
+
+Inject the following values into `project_config.yaml` (append/overwrite these keys only):
+
+```yaml
+target_scope: stories_specific
+target_names:
+  - "{{story_title}}"
+```
+
+Where `{{story_title}}` is the H1 title extracted from the story file.
+
+#### D. Execute Story Content Sync (sa-jira-sync-api Step-05 Logic, Silent Mode)
+
+Load and execute the logic of `step-05-stories.md` from the sa-jira-sync-api workflow with the following **silent mode rules** (these override any interactive elements in that step file):
+
+- **SKIP all menus** — do not display or wait for any user option (`[C]`, `[S]`, `[E]`, etc.)
+- **SKIP the Pre-flight Epic validation prompts** — if an unsynced parent epic is found, log `⚠️ Parent Epic not yet synced to Jira. Story creation may fail.` and continue.
+- **SKIP Section 8 (Present MENU OPTIONS)** — do not display final menu.
+- Process ONLY the story matching `{{story_title}}` (enforced by `target_scope: stories_specific`).
+- All Node.js API calls use the `access_token` refreshed in Section B.
+- After this section: the story and all its tasks/subtasks exist in Jira and `{{jira_key}}` is available from the story file's `## Jira Information` section.
+
+If story sync fails (API error):
+- Output: `❌ Story sync failed: {{error}}. Skipping "done" transition.`
+- Proceed to Section F (log) and then step-07.
+
+#### E. Transition Story and All Subtasks to Done (Node.js, Silent)
+
+After the story is confirmed in Jira (has `{{jira_key}}`):
+
+1. **Transition Parent Story:**
+   - Node.js: `GET https://api.atlassian.com/ex/jira/{{cloud_id}}/rest/api/3/issue/{{jira_key}}/transitions` with `Bearer {{access_token}}`
+   - Find transition where `to.statusCategory.key == "done"` (or name contains "Done"/"Listo"/"Finalizada")
+   - Node.js: `POST .../transitions` body: `{ "transition": { "id": "{{found_id}}" } }`
+   - Output: `✅ {{jira_key}} → Done`
+
+2. **Cascade: Transition all Subtasks:**
+   - Node.js: `GET .../issue/{{jira_key}}` → extract `fields.subtasks`
+   - For each subtask:
+     - Get transitions: `GET .../issue/{{subtask_key}}/transitions`
+     - Find "done" transition id
+     - Execute: `POST .../issue/{{subtask_key}}/transitions` body: `{ "transition": { "id": "{{found_id}}" } }`
+   - If any subtask transition fails: log `⚠️ Subtask {{subtask_key}} transition failed: {{error}}` and continue to next.
+   - Output: `✅ Subtasks → Done`
+
+3. **Update Markdown Tables in Story File:**
+   - Read `{{story_path}}`
+   - In `## Jira Information`: add column `| Jira State |` with value `| **Done** |`
+   - In `## Synced Tasks`: add column `| Jira State |` with value `| **Done** |` for each row
+   - Save file.
+
+#### F. Append Result to Output File
+
+Append to `{outputFile}`:
+
+```markdown
+## Jira Sync (Automated via sa-jira-sync-api)
+- **Story**: {{story_title}}
+- **Jira Key**: {{jira_key}}
+- **Story Content Sync**: [Created/Updated/Skipped (already existed)]
+- **Story Transition**: Done ✅
+- **Subtasks Transitioned**: [N subtasks → Done ✅ / Failed: list]
+- **Infrastructure**: Node.js direct API (OAuth shared with get-features)
+```
+
+Update frontmatter of `{outputFile}`: `stepsCompleted: [1, 2, 3, 4, 5, 6]`
+
+Output: `✅ Jira sync complete. Proceeding to commit...`
+
+Then **immediately load, read, and execute step-07-commit-push.md** — no menu, no waiting for user input.

package/siesa-agents/bmm/workflows/4-implementation/create-story/workflow_ext.md

@@ -27,4 +27,19 @@
 3. LOAD the FULL `@{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/data/company-standards/mastercrud-use-reference.md` — MasterCrud is the highest-level orchestrator component in Siesa UI Kit. It coordinates data grids, forms, filters, and CRUD operations into a unified, configurable interface. **You MUST apply its API contract and configuration patterns whenever the story involves a CRUD screen,   data grid, or form-based UI.** 
 
 **STEP 4: APPLY TO THE STORY**
-- You MUST enforce any system rules, design patterns, testing requirements, or UI guidelines found in the `technical-preference.md` file into the Acceptance Criteria and Technical Details of the user story you are writing. DO NOT write the story without integrating these rules if they exist.
+- You MUST enforce any system rules, design patterns, testing requirements, or UI guidelines found in the `technical-preference.md` file into the Acceptance Criteria and Technical Details of the user story you are writing. DO NOT write the story without integrating these rules if they exist.
+
+# MANDATORY RULE: CREATE STORY WORKFLOW
+
+**TRIGGER:** Every time the user requests a CREATE STORY, such as `/create-story`.
+
+**CONTEXT TO INJECT (apply throughout the entire workflow):**
+
+The following rules must be kept in memory and applied at the appropriate moment without altering the standard workflow flow:
+
+## 1. Sub-agents: only when invoked via quick-dev
+
+Sub-agents **must NOT be used** when the code review workflow is invoked directly (e.g., `/create-story`). Sub-agents are only permitted when the workflow is triggered as part of **quick-dev** (e.g., `/quick-dev`).
+
+- If invoked directly → follow the standard sequential workflow steps without spawning any sub-agents.
+- If invoked from quick-dev → sub-agents may be used as defined by the quick-dev orchestration.

package/siesa-agents/bmm/workflows/4-implementation/dev-story/workflow_ext.md

@@ -100,3 +100,10 @@ Example: `develop-legacy-erp-nomina-gaduranb-rq1234-nueva-interfaz`
    - Run `git worktree add ../wt-{{folder_name}}/{{folder_name}}-{{target_branch}} -b {{target_branch}}`.
    - Run `cd ../wt-{{folder_name}}/{{folder_name}}-{{target_branch}}`.
    - Output: `✨ Created and switched to new branch: {{target_branch}}`.
+
+## 4. Sub-agents: only when invoked via quick-dev
+
+Sub-agents **must NOT be used** when the code review workflow is invoked directly (e.g., `/dev-story`). Sub-agents are only permitted when the workflow is triggered as part of **quick-dev** (e.g., `/quick-dev`).
+
+- If invoked directly → follow the standard sequential workflow steps without spawning any sub-agents.
+- If invoked from quick-dev → sub-agents may be used as defined by the quick-dev orchestration.

package/siesa-agents/sa/sa-jira-sync-api/jira-sync-api.md

@@ -0,0 +1,246 @@
+---
+name: jira-sync-api
+description: Query Jira and return a minimal hierarchy of Epics → Stories → Subtasks for a given project and epic status. Returns only id, key, name, and status for each level. Use when the user needs to inspect or export the epic/story/subtask structure from siesa-team or siesa-test-sandbox.
+---
+
+Handle the Jira sync request: **$ARGUMENTS**
+
+Parse arguments:
+- First positional arg → `PROJECT_KEY` (e.g. `PPS`)
+- `--status "..."` → filter epics by this status name (default: `En curso`)
+- If no `PROJECT_KEY` is provided, prompt the user for one.
+
+---
+
+## Configuration
+
+### Paths
+| Resource | Path |
+|----------|------|
+| Working directory | `RUTA-PROJECT-ACTUAL` |
+| Output file | `_bmad-output/planning-artifacts/jira-sync/{PROJECT-KEY}-sync.md` |
+| OAuth config | `.claude/commands/get-features/oauth-config.json` |
+| Tokens | `.claude/commands/get-features/tokens.json` |
+| OAuth login script | `.claude/commands/get-features/oauth-login.js` |
+
+### Minimal fields extracted per level
+| Level | Fields kept |
+|-------|-------------|
+| Epic | `id`, `key`, `summary` (name), `status.name` |
+| Story | `id`, `key`, `summary` (name), `status.name` |
+| Subtask | `id`, `key`, `summary` (name), `status.name` |
+
+> All other fields returned by the API (self, avatarUrls, iconUrl, project, assignee,
+> description, statusCategory, priority, expand, etc.) are **discarded immediately**
+> after the HTTP response is received — never written to disk or displayed.
+
+---
+
+## Step 1 — Authenticate
+
+Reuse the existing OAuth infrastructure from `get-features`:
+
+Check whether **Tokens** path exists and contains a `refresh_token`:
+
+- **No `tokens.json` or no `refresh_token`** → run the login script:
+  ```
+  node .claude/commands/get-features/oauth-login.js
+  ```
+  Wait until `tokens.json` is created. Inform the user:
+  ```
+  Opening browser for Jira login...
+  Waiting for authentication to complete.
+  ```
+
+- **`tokens.json` exists with `refresh_token`** → silently refresh using Node.js inline:
+  ```js
+  // Read oauth-config.json and tokens.json
+  // POST https://auth.atlassian.com/oauth/token
+  // Body: { grant_type, client_id, client_secret, refresh_token }
+  // Save new access_token (and refresh_token if returned) back to tokens.json
+  ```
+
+**Never use `/dev/stdin` — it does not work on Windows.**
+
+---
+
+## Step 2 — Resolve instance
+
+Call `GET https://api.atlassian.com/oauth/token/accessible-resources`.
+
+- Read `default_instance` from **OAuth config**.
+- If set, use it silently (no prompt).
+- If not set, list instances and prompt the user to select one using a temporary readline `.js` file (delete after use).
+
+Save or confirm `default_instance` in **OAuth config** after resolution.
+
+---
+
+## Step 3 — Resolve project
+
+- If `PROJECT_KEY` was provided as an argument → use it directly, no prompt.
+- If not provided → fetch projects for the instance:
+  ```
+  GET https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3/project/search?maxResults=100
+  ```
+  Display list and prompt with readline. Save selection as `default_project` in **OAuth config**.
+
+---
+
+## Step 4 — Fetch Epics (filtered by status)
+
+```
+POST https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3/search/jql
+```
+```json
+{
+  "jql": "project = {KEY} AND issuetype = Epic AND status = \"{EPIC_STATUS}\" ORDER BY key ASC",
+  "maxResults": 50,
+  "fields": ["id", "key", "summary", "status"]
+}
+```
+
+**Pagination:** if `isLast: false`, fetch next pages using `nextPageToken`.
+
+**Strip immediately** — for each issue in the response, extract only:
+```js
+const epic = {
+  id:     issue.id,
+  key:    issue.key,
+  name:   issue.fields.summary,
+  status: issue.fields.status.name
+};
+```
+Discard everything else. Build `epics[]` array.
+
+If no epics are found for the given status, inform the user and exit.
+
+---
+
+## Step 5 — Fetch Stories per Epic
+
+For each epic key, query its direct children that are Stories:
+
+```
+POST https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3/search/jql
+```
+```json
+{
+  "jql": "project = {KEY} AND issuetype = Story AND parent = {EPIC_KEY} ORDER BY key ASC",
+  "maxResults": 100,
+  "fields": ["id", "key", "summary", "status", "subtasks"]
+}
+```
+
+**Pagination:** handle `nextPageToken` if `isLast: false`.
+
+**Strip immediately:**
+```js
+const story = {
+  id:       issue.id,
+  key:      issue.key,
+  name:     issue.fields.summary,
+  status:   issue.fields.status.name,
+  subtasks: (issue.fields.subtasks ?? []).map(s => ({
+    id:  s.id,
+    key: s.key
+    // name and status fetched in Step 6
+  }))
+};
+```
+
+> **Note:** If your project uses Tasks instead of Stories at this level, replace
+> `issuetype = Story` with `issuetype in (Story, Task)` — adjust per project convention.
+
+---
+
+## Step 6 — Fetch Subtask details
+
+The `subtasks` array from Step 5 only provides `id` and `key` (Jira does not return
+`summary` or `status` for subtasks inline without a full issue fetch).
+
+Batch-fetch subtask details using JQL on their keys:
+
+```
+POST https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3/search/jql
+```
+```json
+{
+  "jql": "issuekey in ({KEY1}, {KEY2}, ...) ORDER BY key ASC",
+  "maxResults": 100,
+  "fields": ["id", "key", "summary", "status"]
+}
+```
+
+Group subtask keys in batches of up to 50 per request to stay within JQL limits.
+
+**Strip immediately:**
+```js
+const subtask = {
+  id:     issue.id,
+  key:    issue.key,
+  name:   issue.fields.summary,
+  status: issue.fields.status.name
+};
+```
+
+---
+
+## Step 7 — Assemble and write output
+
+Build the final structure in memory:
+
+```
+epics[]
+  └── stories[]
+        └── subtasks[]
+```
+
+Write to **Output file** (replace `{PROJECT-KEY}` in path):
+
+```markdown
+# Jira Sync — {PROJECT-KEY} — {Project Name}
+
+**Instance:** {instance URL}
+**Epic status filter:** {EPIC_STATUS}
+**Query date:** {YYYY-MM-DD HH:MM}
+**Epics:** {count} | **Stories:** {count} | **Subtasks:** {count}
+
+---
+
+## {EPIC-KEY} — {Epic Name}
+**ID:** {id} | **Status:** {status}
+
+### {STORY-KEY} — {Story Name}
+**ID:** {id} | **Status:** {status}
+
+#### {SUBTASK-KEY} — {Subtask Name}
+**ID:** {id} | **Status:** {status}
+
+---
+```
+
+Repeat the Epic → Story → Subtask block for every epic found.
+
+After writing, print to the user:
+```
+✅ Sync complete.
+   File: _bmad-output/planning-artifacts/jira-sync/{PROJECT-KEY}-sync.md
+   Epics: X  |  Stories: Y  |  Subtasks: Z
+```
+
+---
+
+## Important rules
+
+- **Language:** output file content must be written in **English**.
+- **Minimal data only:** never write `self`, `avatarUrls`, `iconUrl`, `description`,
+  `assignee`, `priority`, `statusCategory`, `expand`, `project`, or any other field
+  beyond `id`, `key`, `name (summary)`, and `status` to the output or to memory longer
+  than the immediate strip step.
+- **No persistent temp files:** use temporary `.js` files only for readline prompts;
+  delete immediately after use.
+- **Always Node.js** for API calls — do not assume Python is available.
+- **Never commit or push** unless the user explicitly asks.
+- **Subtask ≠ Task:** this command targets `issuetype = Subtask` (children of Stories),
+  not standalone Tasks at the story level.

package/siesa-agents/sa/sync-epics-stories/data/templates/subtask-template.json

@@ -0,0 +1,18 @@
+{
+  "_comment": "Template for adding nested sub-task bullets as a comment on a Jira Sub-task. Uses Atlassian Document Format (ADF) required by Jira Cloud REST API v3.",
+  "body": {
+    "type": "doc",
+    "version": 1,
+    "content": [
+      {
+        "type": "heading",
+        "attrs": { "level": 3 },
+        "content": [{ "type": "text", "text": "Sub-tasks" }]
+      },
+      {
+        "type": "bulletList",
+        "content": "{{nested_bullets_adf_list_items}}"
+      }
+    ]
+  }
+}

package/{bmad/bmm/workflows → siesa-agents/sa}/sync-epics-stories/steps/step-01-init.md

@@ -3,7 +3,7 @@ name: 'step-01-init'
 description: 'Initialize the Jira synchronization workflow by detecting continuation state'
 
 # Path Definitions
-workflow_path: '{project-root}/_bmad/bmm/workflows/sync-epics-stories'
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/sync-epics-stories'
 
 # File References
 thisStepFile: '{workflow_path}/steps/step-01-init.md'
@@ -11,8 +11,9 @@ nextStepFile: '{workflow_path}/steps/step-02-setup.md'
 workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{project-root}/_bmad-output/jira_docs/project_config.yaml' # Using config file as main state tracker
 continueFile: '{workflow_path}/steps/step-01b-continue.md'
-# Input Files
-epicsFile: '{output_folder}/planning-artifacts/epics.md'
+# Input Files — Epics (check folder first, then single file)
+epicsFolder: '{output_folder}/planning-artifacts/epics/'
+epicsFileFallback: '{output_folder}/planning-artifacts/epics.md'
 storiesFolder: '{output_folder}/implementation-artifacts/'
 
 # Task References
@@ -87,12 +88,16 @@ If no config exists or no `stepsCompleted`:
 
 #### A. Input Document Discovery
 
-This workflow requires existing artifacts:
+This workflow requires existing artifacts. **Check epic sources in this order:**
 
-- Check existence of `{epicsFile}`
-- Check for Markdown files in `{storiesFolder}` (e.g., `*.md`)
+1. **First:** Check if `{epicsFolder}` exists AND contains `*.md` files (sharded epics — one file per feature/epic group).
+2. **Fallback:** If the folder does not exist or is empty, check if `{epicsFileFallback}` exists (single monolithic `epics.md`).
+3. **If neither exists:** WARN the user.
 
-If files are missing, WARN the user: "I cannot find `epics.md` or any story files in `implementation-artifacts/`. Please ensure artifacts exist before synchronizing."
+Also check:
+- Markdown files in `{storiesFolder}/stories/` (e.g., `*.md`)
+
+If no epic source AND no story files are found, WARN the user: "I cannot find epic files in `planning-artifacts/epics/` (nor `epics.md`) or story files in `implementation-artifacts/stories/`. Please ensure artifacts exist before synchronizing."
 
 #### B. Create Initial State (Virtual)
 

package/{bmad/bmm/workflows → siesa-agents/sa}/sync-epics-stories/steps/step-01b-continue.md

@@ -3,7 +3,7 @@ name: 'step-01b-continue'
 description: 'Handle workflow continuation from previous session'
 
 # Path Definitions
-workflow_path: '{project-root}/_bmad/bmm/workflows/sync-epics-stories'
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/sync-epics-stories'
 
 # File References
 thisStepFile: '{workflow_path}/steps/step-01b-continue.md'