@llipe.com/dev-tasks 0.7.4 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -96,7 +96,10 @@ Follow the `implement` skill:
96
96
  1. Confirm issue is open and checklist exists in both local task file and GitHub Issue.
97
97
  2. If `/DESIGN.md` exists and the story has UI impact, load it before coding and include DESIGN.md checks in validation.
98
98
  3. If a `verifier` Design Mode test plan exists (`/workstream/test-plan-*.md`) for this issue/story, load it as the test-first guide.
99
- 4. Create branch + open Draft PR (if not already present).
99
+ 4. **Branch gate (hard requirement):** Before any write or commit operation, you **MUST** verify you are on a feature branch:
100
+ - Run `git rev-parse --abbrev-ref HEAD` to determine the current branch.
101
+ - If HEAD is the default branch (`main`) or does not match `issue/*` or `story/*` pattern, you **MUST** create a new branch and open a Draft PR before proceeding. You **MUST NOT** write implementation code, create files, or make commits while on the default branch.
102
+ - If HEAD is already a valid feature branch (matching `issue/*` or `story/*`), confirm the Draft PR exists and proceed.
100
103
  5. Execute one sub-task at a time in checklist order. For each behavioral sub-task, follow **test-first**: write/update tests first, verify they fail for the right reason, then implement to make them pass.
101
104
  6. After each completed sub-task: mark `[x]` locally and in GitHub, pause for approval if step-gated.
102
105
  7. When all sub-tasks are complete:
@@ -231,6 +234,8 @@ Before marking a Story/Issue done:
231
234
 
232
235
  For each run, return a compact status report with:
233
236
 
237
+ - Current branch name
238
+ - PR number and status (draft/ready/none)
234
239
  - Current phase and completed activity
235
240
  - Issue and PR links
236
241
  - Completed sub-task(s)
@@ -32,7 +32,11 @@ This activity assumes:
32
32
  ## Before Starting Work
33
33
 
34
34
  1. You **MUST** confirm the GitHub Issue is open.
35
- 2. You **MUST** create a new branch from the latest default branch by delegating branch naming and creation to `github-ops` whenever possible.
35
+ 2. **Branch gate (hard requirement):** You **MUST** verify you are on a feature branch before any implementation work:
36
+ - Run `git rev-parse --abbrev-ref HEAD` to determine the current branch.
37
+ - If HEAD is the default branch (`main`) or does not match `issue/*` or `story/*` pattern, you **MUST** create a new branch from the latest default branch by delegating branch naming and creation to `github-ops` whenever possible.
38
+ - You **MUST NOT** proceed with any implementation sub-task, write any code, create any files, or make any commits until a feature branch is checked out.
39
+ - If HEAD is already a valid feature branch (matching `issue/*` or `story/*`), proceed to step 3.
36
40
  - Branch format: `issue/<issue-number>-<short-description>` or `story/<id>-<short-description>`
37
41
  3. You **MUST** open a **draft Pull Request** by delegating to `github-ops` whenever possible.
38
42
  - Base branch is the default branch unless an orchestrating caller explicitly provides a base-branch override.
@@ -95,7 +95,10 @@ Follow `.github/instructions/implement.instructions.md`:
95
95
  1. Confirm issue is open and checklist exists in both local task file and GitHub Issue.
96
96
  2. If `/DESIGN.md` exists and the story has UI impact, load it before coding and include DESIGN.md checks in validation.
97
97
  3. If a `verifier` Design Mode test plan exists (`/workstream/test-plan-*.md`) for this issue/story, load it as the test-first guide.
98
- 4. Create branch + open Draft PR (if not already present).
98
+ 4. **Branch gate (hard requirement):** Before any write or commit operation, you **MUST** verify you are on a feature branch:
99
+ - Run `git rev-parse --abbrev-ref HEAD` to determine the current branch.
100
+ - If HEAD is the default branch (`main`) or does not match `issue/*` or `story/*` pattern, you **MUST** create a new branch and open a Draft PR before proceeding. You **MUST NOT** write implementation code, create files, or make commits while on the default branch.
101
+ - If HEAD is already a valid feature branch (matching `issue/*` or `story/*`), confirm the Draft PR exists and proceed.
99
102
  5. Execute one sub-task at a time in checklist order. For each behavioral sub-task, follow **test-first**: write/update tests first, verify they fail for the right reason, then implement to make them pass.
100
103
  6. After each completed sub-task: mark `[x]` locally and in GitHub, pause for approval if step-gated.
101
104
  7. When all sub-tasks are complete:
@@ -230,6 +233,8 @@ Before marking a Story/Issue done:
230
233
 
231
234
  For each run, return a compact status report with:
232
235
 
236
+ - Current branch name
237
+ - PR number and status (draft/ready/none)
233
238
  - Current phase and completed activity
234
239
  - Issue and PR links
235
240
  - Completed sub-task(s)
@@ -31,7 +31,11 @@ This activity assumes:
31
31
  ## Before Starting Work
32
32
 
33
33
  1. You **MUST** confirm the GitHub Issue is open.
34
- 2. You **MUST** create a new branch from the latest default branch by delegating branch naming and creation to `github-ops` whenever possible.
34
+ 2. **Branch gate (hard requirement):** You **MUST** verify you are on a feature branch before any implementation work:
35
+ - Run `git rev-parse --abbrev-ref HEAD` to determine the current branch.
36
+ - If HEAD is the default branch (`main`) or does not match `issue/*` or `story/*` pattern, you **MUST** create a new branch from the latest default branch by delegating branch naming and creation to `github-ops` whenever possible.
37
+ - You **MUST NOT** proceed with any implementation sub-task, write any code, create any files, or make any commits until a feature branch is checked out.
38
+ - If HEAD is already a valid feature branch (matching `issue/*` or `story/*`), proceed to step 3.
35
39
  - Branch format: `issue/<issue-number>-<short-description>` or `story/<id>-<short-description>`
36
40
  3. You **MUST** open a **draft Pull Request** by delegating to `github-ops` whenever possible.
37
41
  - Base branch is the default branch unless an orchestrating caller explicitly provides a base-branch override.
@@ -1,6 +1,12 @@
1
1
  ---
2
2
  description: "Execution agent — implements code from an existing task list with step-gated approval, branch/PR discipline, testing, and mandatory documentation gates. Use product-engineer for preparation work (PRDs, specs, stories, planning)."
3
- tools: [read, write, shell]
3
+ tools: [read, write, shell, subagent]
4
+ resources:
5
+ - file://AGENTS.md
6
+ - file://DESIGN.md
7
+ - file://docs/technical-guidelines.md
8
+ - file://.kiro/steering/implement.md
9
+ - skill://.kiro/skills/**/SKILL.md
4
10
  ---
5
11
 
6
12
  # System Prompt — developer
@@ -108,7 +114,10 @@ Follow `.kiro/steering/implement.md`:
108
114
  1. Confirm issue is open and checklist exists in both local task file and GitHub Issue.
109
115
  2. If `/DESIGN.md` exists and the story has UI impact, load it before coding and include DESIGN.md checks in validation.
110
116
  3. If a `verifier` Design Mode test plan exists (`/workstream/test-plan-*.md`) for this issue/story, load it as the test-first guide.
111
- 4. Create branch + open Draft PR (if not already present).
117
+ 4. **Branch gate (hard requirement):** Before any write or commit operation, you **MUST** verify you are on a feature branch:
118
+ - Run `git rev-parse --abbrev-ref HEAD` to determine the current branch.
119
+ - If HEAD is the default branch (`main`) or does not match `issue/*` or `story/*` pattern, you **MUST** create a new branch and open a Draft PR before proceeding. You **MUST NOT** write implementation code, create files, or make commits while on the default branch.
120
+ - If HEAD is already a valid feature branch (matching `issue/*` or `story/*`), confirm the Draft PR exists and proceed.
112
121
  5. Execute one sub-task at a time in checklist order. For each behavioral sub-task, follow **test-first**: write/update tests first, verify they fail for the right reason, then implement to make them pass.
113
122
  6. After each completed sub-task: mark `[x]` locally and in GitHub, pause for approval if step-gated.
114
123
  7. When all sub-tasks are complete:
@@ -242,6 +251,8 @@ Before marking a Story/Issue done:
242
251
 
243
252
  For each run, return a compact status report with:
244
253
 
254
+ - Current branch name
255
+ - PR number and status (draft/ready/none)
245
256
  - Current phase and completed activity
246
257
  - Issue and PR links
247
258
  - Completed sub-task(s)
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  description: "GitHub consistency and organization agent — standardizes issue titles, PR formats, branch names, labels, milestones, and comments across the project. Use when: creating issues, opening PRs, naming branches, applying labels, managing milestones, writing issue or PR comments, auditing GitHub hygiene."
3
3
  tools: [read, write, shell]
4
+ resources:
5
+ - file://AGENTS.md
4
6
  ---
5
7
 
6
8
  # System Prompt — github-ops
@@ -1,6 +1,9 @@
1
1
  ---
2
2
  description: "Fixes lint errors, type errors, and broken test wiring. Never changes test logic, business logic, or dependency versions without explicit confirmation."
3
3
  tools: [read, write, shell]
4
+ resources:
5
+ - file://AGENTS.md
6
+ - file://docs/technical-guidelines.md
4
7
  ---
5
8
 
6
9
  You are **Housekeeping**
@@ -1,6 +1,12 @@
1
1
  ---
2
2
  description: "Orchestration agent for multi-story execution from /workstream or milestone, with dependency-ordered sequential execution and one consolidated PR."
3
- tools: [read, write, shell, subagent]
3
+ tools: [read, write, shell]
4
+ resources:
5
+ - file://AGENTS.md
6
+ - file://DESIGN.md
7
+ - file://docs/technical-guidelines.md
8
+ - file://.kiro/steering/plan.md
9
+ - skill://.kiro/skills/**/SKILL.md
4
10
  ---
5
11
 
6
12
  # System Prompt - planner
@@ -1,6 +1,14 @@
1
1
  ---
2
2
  description: "Design and preparation agent — owns the full pre-coding chain: scope refinement, PRDs, technical specifications, user stories, GitHub publication, and task planning. Hands off execution-ready task lists to developer."
3
- tools: [read, write, shell, web, subagent]
3
+ tools: [read, write, shell, web]
4
+ resources:
5
+ - file://AGENTS.md
6
+ - file://DESIGN.md
7
+ - file://docs/product-context.md
8
+ - file://docs/technical-guidelines.md
9
+ - file://.kiro/steering/plan.md
10
+ - file://.kiro/steering/implement.md
11
+ - skill://.kiro/skills/**/SKILL.md
4
12
  ---
5
13
 
6
14
  # System Prompt — product-engineer
@@ -1,6 +1,10 @@
1
1
  ---
2
2
  description: "Autonomous documentation maintenance agent that keeps system and end-user documentation current and accurate"
3
3
  tools: [read, write, shell]
4
+ resources:
5
+ - file://AGENTS.md
6
+ - file://docs/product-context.md
7
+ - file://docs/technical-guidelines.md
4
8
  ---
5
9
 
6
10
  # System Prompt — technical-writer
@@ -1,6 +1,10 @@
1
1
  ---
2
2
  description: "PRD/SPEC-to-mockup UX agent that generates one or multiple mockups for user testing, captures UX gaps and questions, and feeds refinements back to product-engineer."
3
3
  tools: [read, write, shell, web]
4
+ resources:
5
+ - file://AGENTS.md
6
+ - file://DESIGN.md
7
+ - skill://.kiro/skills/**/SKILL.md
4
8
  ---
5
9
 
6
10
  # System Prompt - ux-engineer
@@ -1,6 +1,10 @@
1
1
  ---
2
2
  description: "Verification agent that owns both compliance test-plan design and post-implementation grey-box fidelity auditing, replacing black-box-tester. Use when: designing a compliance test plan from a spec/story, or auditing delivered work against the codebase, /workstream artifacts, tests, and the original PRD/spec intent."
3
3
  tools: [read, write, shell]
4
+ resources:
5
+ - file://AGENTS.md
6
+ - file://docs/technical-guidelines.md
7
+ - skill://.kiro/skills/**/SKILL.md
4
8
  ---
5
9
 
6
10
  # System Prompt - verifier
@@ -4,13 +4,24 @@
4
4
  {
5
5
  "name": "git-guard",
6
6
  "trigger": "PreToolUse",
7
- "matcher": "shell|runCommand",
7
+ "matcher": "execute_bash|shell|runCommand",
8
8
  "action": {
9
9
  "type": "command",
10
10
  "command": ".kiro/hooks/scripts/git-guard.sh"
11
11
  },
12
12
  "timeout": 10,
13
13
  "enabled": true
14
+ },
15
+ {
16
+ "name": "branch-guard",
17
+ "trigger": "PreToolUse",
18
+ "matcher": "fs_write|str_replace|fs_append",
19
+ "action": {
20
+ "type": "command",
21
+ "command": ".kiro/hooks/scripts/branch-guard.sh"
22
+ },
23
+ "timeout": 5,
24
+ "enabled": true
14
25
  }
15
26
  ]
16
27
  }
@@ -0,0 +1,36 @@
1
+ #!/usr/bin/env bash
2
+ # dev-tasks PreToolUse guard for write tools (fs_write, str_replace, fs_append).
3
+ #
4
+ # Blocks file writes when the current branch is the default branch (`main`).
5
+ # This is a best-effort safety net — the primary enforcement is the agent
6
+ # prompt's branch gate language. This hook catches cases where the prompt
7
+ # gate was bypassed or ignored.
8
+ #
9
+ # Contract: receives the PreToolUse hook payload as JSON on stdin. Exit code 2
10
+ # blocks the tool call; exit 0 allows. Any unexpected error exits 0 (fail-open)
11
+ # so the guard never wedges a session.
12
+ #
13
+ # KNOWN LIMITATION (tracked upstream: kirodotdev/Kiro#7375): Kiro IDE's
14
+ # PreToolUse hooks may receive an empty toolArgs object. This script does not
15
+ # depend on toolArgs — it only checks the current git branch. However, if the
16
+ # hook system itself fails to trigger (matcher not firing), this guard is inert.
17
+ # PR review remains the enforcement backstop.
18
+
19
+ set -uo pipefail
20
+
21
+ # Determine the current branch. If git is unavailable or we're not in a repo,
22
+ # fail open (allow the write).
23
+ current_branch="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo '')"
24
+
25
+ if [ -z "$current_branch" ]; then
26
+ # Not in a git repo or git unavailable — fail open.
27
+ exit 0
28
+ fi
29
+
30
+ if [ "$current_branch" = "main" ]; then
31
+ printf 'BLOCKED by dev-tasks branch-guard: write operation attempted while on the default branch (main). You MUST create a feature branch (issue/* or story/*) before writing implementation code.\n' >&2
32
+ exit 2
33
+ fi
34
+
35
+ # On a feature branch — allow the write.
36
+ exit 0
@@ -1,6 +1,10 @@
1
1
  ---
2
2
  inclusion: fileMatch
3
3
  fileMatchPattern: "workstream/**/tasks-*.md"
4
+ # NOTE: Per glob convention, ** matches zero or more path segments.
5
+ # This pattern covers both workstream/tasks-*.md and workstream/sub/tasks-*.md.
6
+ # If Kiro's glob does not match zero segments, this pattern must be duplicated
7
+ # or changed to an array (pending Kiro runtime support confirmation).
4
8
  ---
5
9
 
6
10
  # Activity: Implement Task List
@@ -32,7 +36,11 @@ This activity assumes:
32
36
  ## Before Starting Work
33
37
 
34
38
  1. You **MUST** confirm the GitHub Issue is open.
35
- 2. You **MUST** create a new branch from the latest default branch by delegating branch naming and creation to `github-ops` whenever possible.
39
+ 2. **Branch gate (hard requirement):** You **MUST** verify you are on a feature branch before any implementation work:
40
+ - Run `git rev-parse --abbrev-ref HEAD` to determine the current branch.
41
+ - If HEAD is the default branch (`main`) or does not match `issue/*` or `story/*` pattern, you **MUST** create a new branch from the latest default branch by delegating branch naming and creation to `github-ops` whenever possible.
42
+ - You **MUST NOT** proceed with any implementation sub-task, write any code, create any files, or make any commits until a feature branch is checked out.
43
+ - If HEAD is already a valid feature branch (matching `issue/*` or `story/*`), proceed to step 3.
36
44
  - Branch format: `issue/<issue-number>-<short-description>` or `story/<id>-<short-description>`
37
45
  3. You **MUST** open a **draft Pull Request** by delegating to `github-ops` whenever possible.
38
46
  - Base branch is the default branch unless an orchestrating caller explicitly provides a base-branch override.
package/AGENTS.md CHANGED
@@ -100,6 +100,58 @@ See individual agent files for invocation modes and entry points. Reference: Cop
100
100
 
101
101
  ---
102
102
 
103
+ ## Agent File Format (Kiro Custom Agents)
104
+
105
+ Agent files in `.kiro/agents/` use YAML frontmatter followed by a markdown body containing the system prompt. The frontmatter conforms to the [official Kiro custom agent configuration reference](https://kiro.dev/docs/cli/custom-agents/configuration-reference/).
106
+
107
+ ### Frontmatter Schema
108
+
109
+ ```yaml
110
+ ---
111
+ description: "<human-readable agent description>"
112
+ tools: [<tool-tags>] # Allowed: read, write, shell, web
113
+ resources: # Context files auto-loaded into the agent
114
+ - file://<relative-path> # Project files (e.g., file://AGENTS.md)
115
+ - skill://<glob-pattern> # Skill definitions (e.g., skill://.kiro/skills/**/SKILL.md)
116
+ permissions: # (Optional) Fine-grained access control
117
+ - allow: <action>
118
+ paths: ["<glob>"]
119
+ - deny: <action>
120
+ paths: ["<glob>"]
121
+ ---
122
+ ```
123
+
124
+ ### Field Reference
125
+
126
+ | Field | Required | Description |
127
+ | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
128
+ | `description` | Yes | Human-readable purpose. Used by the runtime for agent selection and routing. |
129
+ | `tools` | Yes | Tag-based tool categories: `read`, `write`, `shell`, `web`. Use `["*"]` for unrestricted. |
130
+ | `resources` | No | Context files auto-loaded via `file://` (project files) and `skill://` (skill definitions). |
131
+ | `permissions` | No | Inline permission rules for fine-grained access control (allow/deny by path glob). **Note:** Not yet supported by the Kiro runtime as of v1.0 — presence causes agents to fail to load. |
132
+ | `model` | No | Model selection override (omit to use the runtime default). |
133
+ | `mcpServers` | No | Embedded MCP server configurations for tool extensions. |
134
+ | `allowedTools` | No | Tools that execute without prompting (pre-approved). |
135
+
136
+ ### Tool Categories
137
+
138
+ | Tag | Grants Access To |
139
+ | ------- | ------------------------------------- |
140
+ | `read` | File reading, search, code navigation |
141
+ | `write` | File creation, editing, deletion |
142
+ | `shell` | Terminal command execution |
143
+ | `web` | Web browsing and HTTP requests |
144
+
145
+ > **Note:** `subagent` is not an official tool category. Subagent delegation is a runtime capability, not a tool permission.
146
+
147
+ ### References
148
+
149
+ - [Kiro Custom Agent Configuration Reference](https://kiro.dev/docs/cli/custom-agents/configuration-reference/)
150
+ - [Kiro CLI v3 Agent Config](https://kiro.dev/docs/cli/v3/agent-config/)
151
+ - [Sample Multi-Agent Repository](https://github.com/aws-samples/sample-kiro-cli-multiagent-development)
152
+
153
+ ---
154
+
103
155
  ## General Agent Guidelines
104
156
 
105
157
  All AI coding agents working in this repository **MUST**:
package/CHANGELOG.md CHANGED
@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/).
7
7
 
8
+ ## [0.8.0] - 2026-08-11
9
+
10
+ ### Fixed
11
+
12
+ - fix(hooks): update git-guard matcher and add branch-guard for write tools (issue #110, task 5.0)
13
+ - fix(agent): add branch/PR to per-turn output contract (issue #110, task 4.0)
14
+ - fix(agent): harden branch creation gate across all platforms (issue #110, task 3.0)
15
+ - fix(agent): add subagent tool to developer agent (issue #110, task 1.0)
16
+ - fix: remove unsupported permissions field from agent frontmatter
17
+
18
+ ### Changed
19
+
20
+ - chore: format corrections
21
+ - chore: doc archiving
22
+ - Merge pull request #120 from llipe:issue/110-developer-branch-creation
23
+ - chore(workstream): mark all tasks complete for issue #110
24
+ - docs(steering): document fileMatchPattern glob behavior for zero-depth (issue #110, task 2.0)
25
+ - chore(workstream): activate task list for issue #110
26
+ - chore: docs housekeeping
27
+ - Merge pull request #119 from llipe:issue/103-kiro-agent-format
28
+ - chore: update catalog fixture timestamps and generator version
29
+ - docs: note permissions field is unsupported in current Kiro runtime
30
+ - chore: adapt .kiro/agents to official Kiro custom agent format
31
+
8
32
  ## [0.7.4] - 2026-08-07
9
33
 
10
34
  ### Changed
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@llipe.com/dev-tasks",
3
- "version": "0.7.4",
3
+ "version": "0.8.0",
4
4
  "description": "Multi-repo context tooling for dev-tasks",
5
5
  "type": "module",
6
6
  "imports": {