steersync 0.3.0__tar.gz → 0.4.0__tar.gz

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.
Files changed (48) hide show
  1. {steersync-0.3.0 → steersync-0.4.0}/CHANGELOG.md +50 -0
  2. steersync-0.3.0/README.md → steersync-0.4.0/PKG-INFO +90 -22
  3. steersync-0.3.0/PKG-INFO → steersync-0.4.0/README.md +58 -53
  4. {steersync-0.3.0 → steersync-0.4.0}/pyproject.toml +20 -14
  5. {steersync-0.3.0 → steersync-0.4.0}/scripts/prepare_release.py +0 -2
  6. {steersync-0.3.0 → steersync-0.4.0}/src/steersync/__init__.py +1 -1
  7. {steersync-0.3.0 → steersync-0.4.0}/src/steersync/cli.py +129 -7
  8. {steersync-0.3.0 → steersync-0.4.0}/src/steersync/config.py +39 -8
  9. {steersync-0.3.0 → steersync-0.4.0}/src/steersync/gitlab.py +0 -2
  10. {steersync-0.3.0 → steersync-0.4.0}/src/steersync/gitops.py +0 -2
  11. {steersync-0.3.0 → steersync-0.4.0}/src/steersync/hooks.py +29 -7
  12. steersync-0.4.0/src/steersync/kiro_rules.py +819 -0
  13. steersync-0.4.0/src/steersync/kiro_version.py +269 -0
  14. {steersync-0.3.0 → steersync-0.4.0}/src/steersync/lint.py +80 -86
  15. {steersync-0.3.0 → steersync-0.4.0}/src/steersync/locking.py +2 -4
  16. {steersync-0.3.0 → steersync-0.4.0}/src/steersync/logging_utils.py +0 -2
  17. {steersync-0.3.0 → steersync-0.4.0}/src/steersync/mcp_server.py +107 -24
  18. steersync-0.4.0/src/steersync/migrate.py +175 -0
  19. {steersync-0.3.0 → steersync-0.4.0}/src/steersync/paths.py +0 -2
  20. {steersync-0.3.0 → steersync-0.4.0}/src/steersync/practices.py +0 -11
  21. {steersync-0.3.0 → steersync-0.4.0}/src/steersync/resources/default_config.yaml +61 -9
  22. {steersync-0.3.0 → steersync-0.4.0}/src/steersync/steering.py +32 -7
  23. {steersync-0.3.0 → steersync-0.4.0}/src/steersync/sync.py +0 -2
  24. {steersync-0.3.0 → steersync-0.4.0}/tests/conftest.py +7 -2
  25. {steersync-0.3.0 → steersync-0.4.0}/tests/test_automation.py +0 -2
  26. {steersync-0.3.0 → steersync-0.4.0}/tests/test_cli.py +3 -2
  27. {steersync-0.3.0 → steersync-0.4.0}/tests/test_collections.py +31 -5
  28. {steersync-0.3.0 → steersync-0.4.0}/tests/test_config.py +5 -2
  29. {steersync-0.3.0 → steersync-0.4.0}/tests/test_gitlab.py +0 -2
  30. {steersync-0.3.0 → steersync-0.4.0}/tests/test_gitops.py +0 -2
  31. {steersync-0.3.0 → steersync-0.4.0}/tests/test_hardening.py +0 -2
  32. {steersync-0.3.0 → steersync-0.4.0}/tests/test_hooks.py +27 -4
  33. steersync-0.4.0/tests/test_kiro_collections.py +156 -0
  34. steersync-0.4.0/tests/test_kiro_rules.py +341 -0
  35. steersync-0.4.0/tests/test_kiro_version.py +187 -0
  36. {steersync-0.3.0 → steersync-0.4.0}/tests/test_lint.py +3 -3
  37. {steersync-0.3.0 → steersync-0.4.0}/tests/test_mcp_server.py +17 -2
  38. steersync-0.4.0/tests/test_migrate.py +111 -0
  39. {steersync-0.3.0 → steersync-0.4.0}/tests/test_practices.py +1 -4
  40. {steersync-0.3.0 → steersync-0.4.0}/tests/test_prepare_release.py +0 -2
  41. {steersync-0.3.0 → steersync-0.4.0}/tests/test_steering.py +0 -2
  42. {steersync-0.3.0 → steersync-0.4.0}/tests/test_sync.py +5 -2
  43. {steersync-0.3.0 → steersync-0.4.0}/.gitignore +0 -0
  44. {steersync-0.3.0 → steersync-0.4.0}/LICENSE +0 -0
  45. {steersync-0.3.0 → steersync-0.4.0}/src/steersync/__main__.py +0 -0
  46. {steersync-0.3.0 → steersync-0.4.0}/src/steersync/errors.py +0 -0
  47. {steersync-0.3.0 → steersync-0.4.0}/steersync.example.yaml +0 -0
  48. {steersync-0.3.0 → steersync-0.4.0}/tests/__init__.py +0 -0
@@ -5,6 +5,56 @@ Keep a Changelog and the project uses semantic versioning.
5
5
 
6
6
  ## [Unreleased]
7
7
 
8
+ ## [0.4.0] - 2026-11-22
9
+
10
+ ### Added
11
+
12
+ - Collections for the rest of the committable Kiro configuration (Kiro IDE 1.5, Kiro CLI 3.5):
13
+ `workflows` (`.kiro/workflows/*.workflow.{json,yaml,yml}` and `~/.kiro/workflows`),
14
+ `sandbox` (`.kiro/settings/sandbox.json`), `kiroignore` (`.kiroignore` at any depth and
15
+ `~/.kiro/settings/kiroignore`) and the opt in `cli-settings` (`.kiro/settings/cli.json`).
16
+ `agents-md` now syncs nested `AGENTS.md` files, and `specs` syncs every file in a spec
17
+ directory (`bugfix.md`, metadata), not only markdown.
18
+ - Schema rules (`steersync.kiro_rules`): hooks need `version: "v1"` and a matching
19
+ `action.command` or `action.prompt`; integer timeouts; `confirm` only on `Stop` command
20
+ hooks; the `SessionEnd`, `PermissionRequest`, `PreCompact` and `PostCompact` triggers, with
21
+ CLI 2.x camelCase names flagged. Agents: V2 format (`toolsSettings` or `allowedTools`
22
+ without `permissions`) is an error because Kiro rewrites such files on load, plus checks
23
+ for `permissions.rules`, 2.x tool names, `use_aws`, `toolAliases`, `keyboardShortcut`,
24
+ resource schemes, home directory paths and inline V3 hooks, for JSON and Markdown agents.
25
+ `mcp.json`: literal secrets in `env`, `headers` and `oauth.clientSecret`, `oauth.mode`,
26
+ `clientMetadataUrl`, timeouts. `sandbox.json`, workspace `cli.json`, workflow recipes
27
+ (node types, unique ids, `repeat` limits, join policies, depth and size) and
28
+ `.kiroignore` syntax.
29
+ - Kiro CLI V3 harness detection: `steersync v3-status`, a harness section in `doctor`, the
30
+ `kiro_v3_status` MCP tool and a once a day reminder from the session hook. Uses only
31
+ `kiro-cli --version` and `kiro-cli settings`, never a chat session.
32
+ - `steersync migrate-hooks` converts `*.kiro.hook` files and CLI 2.x inline agent hooks into
33
+ standalone `.kiro/hooks/*.json` files (dry run by default).
34
+ - The `steersync-mcp` entry point, MCP tool titles and read only, destructive and idempotent
35
+ annotations, server version and title, `confirm` for a forced pull, and logs on stderr.
36
+
37
+ ### Changed
38
+
39
+ - The rendered `mcp.json` entry runs `uvx --from "steersync[mcp]==<version>" steersync mcp`
40
+ (the previous `uvx steersync mcp` lacked the `mcp` extra) and auto approves the read only
41
+ tools.
42
+ - Collections may share a directory when each selects its files by literal name and the
43
+ names do not overlap. Hidden files are synced when a pattern names them literally, and
44
+ excluded trees such as `node_modules` are no longer walked.
45
+ - Dependency floors: click 8.5.1, pydantic 2.14.4, PyYAML 6.0.4, pymarkdownlnt 0.9.42,
46
+ hatchling 1.33, pytest 9.2, ruff 0.17.6, bandit 1.9, pip-audit 2.10. pytest uses its
47
+ native TOML configuration, coverage must stay at 90 per cent, CI also tests Python 3.15
48
+ and runs ty as an advisory check, and `from __future__ import annotations` is gone
49
+ (Python 3.14 defers annotations).
50
+
51
+ ### Fixed
52
+
53
+ - The Kiro session hook command `steersync pull --quiet --best-effort` failed with "No such
54
+ option: --quiet"; `pull` now accepts `-q/--quiet`.
55
+ - `steersync lint FILE` crashed for a file outside the repository, and
56
+ `steersync lint --profile P DIR` used the steering file patterns for every profile.
57
+
8
58
  ## [0.3.0] - 2026-10-13
9
59
 
10
60
  ### Added
@@ -1,7 +1,42 @@
1
+ Metadata-Version: 2.5
2
+ Name: steersync
3
+ Version: 0.4.0
4
+ Summary: Sync Kiro configuration (steering, specs, skills, agents, hooks, workflows, settings) with a central git repository.
5
+ Project-URL: Homepage, https://github.com/SCGIS-Wales/steersync
6
+ Project-URL: Repository, https://github.com/SCGIS-Wales/steersync
7
+ Project-URL: Issues, https://github.com/SCGIS-Wales/steersync/issues
8
+ Project-URL: Changelog, https://github.com/SCGIS-Wales/steersync/blob/main/CHANGELOG.md
9
+ Author-email: Dejan Gregor <dejan.gregor@gmail.com>
10
+ License-Expression: Apache-2.0
11
+ License-File: LICENSE
12
+ Keywords: agents,developer-experience,git,hooks,kiro,kiro-cli,mcp,pre-push,steering,workflows
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Environment :: Console
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3 :: Only
19
+ Classifier: Programming Language :: Python :: 3.14
20
+ Classifier: Programming Language :: Python :: 3.15
21
+ Classifier: Topic :: Software Development :: Version Control :: Git
22
+ Classifier: Typing :: Typed
23
+ Requires-Python: >=3.14
24
+ Requires-Dist: click<9,>=8.5.1
25
+ Requires-Dist: pydantic<3,>=2.14.4
26
+ Requires-Dist: pymarkdownlnt<1,>=0.9.42
27
+ Requires-Dist: python-frontmatter<2,>=1.3
28
+ Requires-Dist: pyyaml<7,>=6.0.4
29
+ Provides-Extra: mcp
30
+ Requires-Dist: mcp<3,>=2.3; extra == 'mcp'
31
+ Description-Content-Type: text/markdown
32
+
1
33
  # steersync
2
34
 
3
- Sync the whole [Kiro](https://kiro.dev) `.kiro/` configuration, steering, specs, skills,
4
- agents, hooks and settings, between developer machines and a central git repository. A plain
35
+ Sync the whole [Kiro](https://kiro.dev) `.kiro/` configuration (steering, specs, skills,
36
+ agents, hooks, settings, the sandbox policy, workflow recipes, prompts, `AGENTS.md` and
37
+ `.kiroignore` files) between developer machines and a central git repository. It targets Kiro
38
+ IDE 1.5 and Kiro CLI 3.5 with the V3 agent harness, and reminds you when a machine is still
39
+ on V2. A plain
5
40
  Python CLI runs from a git pre-push hook and shells out to the `git` binary, so your existing
6
41
  SSH agent or credential helper does the authentication. An MCP server and Kiro session hooks
7
42
  are optional layers on top of the same core.
@@ -24,23 +59,33 @@ layout; each one is configurable and new ones are added with a single YAML block
24
59
  | Collection | Workspace | Global (`~/.kiro`) | Central directory | Files | Lint profile |
25
60
  |---|---|---|---|---|---|
26
61
  | `steering` | `.kiro/steering` | `steering` | `steering/` | `**/*.md` | `steering`: Kiro front matter, references, secrets, markdown |
27
- | `specs` | `.kiro/specs` | none | `specs/` | `**/*.md` | `markdown`: secrets and markdown style |
62
+ | `specs` | `.kiro/specs` | none | `specs/` | every file in each spec (`requirements.md` or `bugfix.md`, `design.md`, `tasks.md`, metadata) | `markdown`: secrets and markdown style |
28
63
  | `skills` | `.kiro/skills` | `skills` | `skills/` | everything (`SKILL.md`, `scripts/`, `references/`, `assets/`) | `skill`: `SKILL.md` needs `name` and `description`, secrets in scripts |
29
- | `agents` | `.kiro/agents` | `agents` | `agents/` | `**/*.json`, `**/*.md` | `agent`: valid JSON with a `name`, flags deprecated `toolsSettings` |
30
- | `hooks` | `.kiro/hooks` | `hooks` | `hooks/` | `**/*.json` | `hooks`: `version`, `hooks[]` with `name`, `trigger`, `action` |
31
- | `settings` | `.kiro/settings` | none | `settings/` | `lsp.json`, `mcp.json` | `settings`: valid JSON, `mcpServers` and `languages` shapes, machine paths |
64
+ | `agents` | `.kiro/agents` | `agents` | `agents/` | `**/*.json`, `**/*.md` (not the `*.json.bak` upgrade backups) | `agent`: V3 universal format, `permissions.rules`, tool names, resources, inline hooks |
65
+ | `hooks` | `.kiro/hooks` | `hooks` | `hooks/` | `**/*.json`, legacy `**/*.kiro.hook` | `hooks`: `version: v1`, triggers, actions, timeouts, `confirm` |
66
+ | `settings` | `.kiro/settings` | none | `settings/` | `lsp.json`, `mcp.json` | `settings`: shapes, literal secrets, OAuth, machine paths |
67
+ | `sandbox` | `.kiro/settings` | none | `sandbox/` | `sandbox.json` | `settings`: `enabled`, `networkAccess` |
68
+ | `cli-settings` (off by default) | `.kiro/settings` | none | `cli-settings/` | `cli.json` | `settings`: rejects global only keys such as `chat.agentEngine` |
69
+ | `workflows` | `.kiro/workflows` | `workflows` | `workflows/` | `**/*.workflow.json`, `.yaml`, `.yml` | `workflow`: the recipe schema of Kiro CLI 3.5 |
32
70
  | `prompts` | `.kiro/prompts` | `prompts` | `prompts/` | `**/*.md` | `prompt`: markdown plus the 50 character name limit |
33
- | `agents-md` | `AGENTS.md` at the root | none | `agents-md/` | `AGENTS.md` | `markdown` (kept in the project repository too) |
34
-
35
- Execute bits on skill scripts survive the round trip, hidden files are never synced, and
36
- files a collection's patterns do not select are never touched on either side. Limit any
71
+ | `agents-md` | the repository | none | `agents-md/` | `**/AGENTS.md` (root and nested) | `markdown` (kept in the project repository too) |
72
+ | `kiroignore` | the repository | `settings` (`kiroignore`) | `kiroignore/` | `**/.kiroignore` | `kiroignore`: gitignore syntax, advice on `.env*` and `*.pem` |
73
+
74
+ Execute bits on skill scripts survive the round trip. Hidden directories are never synced,
75
+ and a hidden file only when a pattern names it (`**/.kiroignore`). Files a collection's
76
+ patterns do not select are never touched on either side, which is why `settings`, `sandbox`
77
+ and `cli-settings` can share `.kiro/settings`. The repository wide collections skip
78
+ `node_modules`, virtual environments, `dist`, `build` and `target` without walking them. Limit any
37
79
  command to some collections with `--collection NAME` (repeatable), list them with
38
80
  `steersync config collections`, and see [docs/central-layout.md](docs/central-layout.md) for
39
81
  a worked example of a full `.kiro/` tree in the central repository.
40
82
 
41
- Not synced on purpose: `~/.kiro/powers/` (installed by Kiro from a registry, not authored),
42
- `~/.kiro/settings/cli.json` and `permissions.yaml` (per user, outside any repository) and
43
- knowledge bases (declared in agent resources, indexed by Kiro). Every path above comes from
83
+ Never synced, by design: workspace permissions (`~/.kiro/workspace-roots/<hash>/permissions.yaml`,
84
+ kept per user so that a cloned repository cannot inject permission rules) and
85
+ `~/.kiro/settings/permissions.yaml`, `~/.kiro/powers/` (installed from a registry),
86
+ `~/.kiro/memories/`, `~/.kiro/sessions/`, `~/.kiro/crew/`, `~/.kiro/settings/cli.json`,
87
+ `managed-settings.json` and knowledge base indexes (the declarations in agent `resources`
88
+ are synced with the agent). Every path above comes from
44
89
  the Kiro configuration scopes documentation; a new kind of content is one YAML block.
45
90
 
46
91
  ## Install
@@ -50,8 +95,11 @@ Requires Python 3.14 or newer and git 2.18 or newer. Every
50
95
  sdist and a `SHA256SUMS` file, with signed build provenance.
51
96
 
52
97
  ```bash
53
- VERSION=0.3.0
98
+ VERSION=0.4.0
54
99
  uv tool install "https://github.com/SCGIS-Wales/steersync/releases/download/v${VERSION}/steersync-${VERSION}-py3-none-any.whl"
100
+ # or run it without installing
101
+ uvx steersync --help
102
+ uvx --from "steersync[mcp]" steersync-mcp
55
103
  # with the MCP server
56
104
  uv tool install "steersync[mcp] @ https://github.com/SCGIS-Wales/steersync/releases/download/v${VERSION}/steersync-${VERSION}-py3-none-any.whl"
57
105
  # verify where the wheel came from
@@ -151,10 +199,12 @@ subdirectory; `pull` and `status` print a warning pointing at them until that is
151
199
  | `steersync init [--write-config] [--hook] [--no-exclude] [--no-kiro] [--mcp-command PATH]` | Prepare a repository: excludes, git hook, Kiro session hook and MCP server entry. |
152
200
  | `steersync install-hook [--force]` | Install or update the chaining pre-push hook. |
153
201
  | `steersync kiro-hook [--engine v2\|v3] [--write]` | Render a Kiro hook that runs `steersync pull --quiet` at session start. |
154
- | `steersync mcp-config [--remote URL]` | Render an `mcp.json` fragment. |
155
- | `steersync mcp` | Run the MCP stdio server. |
202
+ | `steersync migrate-hooks [--write]` | Convert `*.kiro.hook` files and CLI 2.x inline agent hooks into `.kiro/hooks/*.json`. Dry run by default; never overwrites or deletes. |
203
+ | `steersync v3-status [--json] [--strict]` | Report the kiro-cli version, `chat.agentEngine` and agents still in the V2 format. `--strict` exits 10 when a reminder applies. |
204
+ | `steersync mcp-config [--command uvx] [--remote URL]` | Render an `mcp.json` fragment. |
205
+ | `steersync mcp` (or `steersync-mcp`) | Run the MCP stdio server. |
156
206
  | `steersync config show\|validate\|default\|collections` | Inspect configuration and the resolved collection directories. |
157
- | `steersync doctor` | Report git version, resolved paths, remote and project slug. |
207
+ | `steersync doctor` | Report git version, resolved paths, remote, project slug and the Kiro CLI harness. |
158
208
 
159
209
  Global options: `--config PATH`, `--log-level`, `--log-format text|json`, `--quiet`.
160
210
 
@@ -259,7 +309,7 @@ Teams that already use [pre-commit](https://pre-commit.com) can use the publishe
259
309
  default_install_hook_types: [pre-commit, pre-push]
260
310
  repos:
261
311
  - repo: https://github.com/SCGIS-Wales/steersync
262
- rev: v0.3.0
312
+ rev: v0.4.0
263
313
  hooks:
264
314
  - id: steersync-push
265
315
  - id: steersync-lint
@@ -307,9 +357,12 @@ The merge request is opened in two ways:
307
357
  ## Validation
308
358
 
309
359
  Each collection runs one lint profile: `steering`, `agent`, `hooks`, `skill`, `settings`,
310
- `prompt`, `markdown`, `json` or `generic`. **Errors** are things Kiro cannot read (front
311
- matter after a blank line, an unknown inclusion mode, invalid JSON, a `SKILL.md` without
312
- `name` and `description`) or secrets; they stop a push. **Warnings** are best practices from
360
+ `prompt`, `workflow`, `kiroignore`, `markdown`, `json` or `generic`. **Errors** are things
361
+ Kiro cannot read or would rewrite (front matter after a blank line, an unknown inclusion
362
+ mode, invalid JSON, a `SKILL.md` without `name` and `description`, a hook without
363
+ `version: "v1"`, a workflow `repeat` without `maxIterations`, an unknown sandbox
364
+ `networkAccess`, a V2 format agent) or secrets, including literal tokens in `mcp.json`
365
+ `env`, `headers` and `oauth.clientSecret`; they stop a push. **Warnings** are best practices from
313
366
  the Kiro documentation, reported objectively and never blocking: a steering file with a
314
367
  numeric prefix, an `auto` description that is not written as a trigger, a `globs` key where
315
368
  Kiro reads `fileMatchPattern`, an agent with `tools: ["*"]` or a `file://.kiro/steering/**`
@@ -329,8 +382,22 @@ and `lint.practices: false` turns the warnings off.
329
382
  fire only in headless runs or with a custom agent active, so treat them as a convenience and
330
383
  keep the git hook as the dependable trigger.
331
384
 
385
+ **Kiro CLI V3.** Kiro CLI 3.0.0 made V3 the default agent harness; V2 still runs but gets no
386
+ new features. `steersync doctor`, `steersync v3-status`, the `kiro_v3_status` MCP tool and
387
+ the session hook (at most once a day) check `kiro-cli --version`, `chat.agentEngine` and your
388
+ agent files. When a reminder applies, run `kiro-cli settings chat.agentEngine v3`, start
389
+ `kiro-cli` and run `/upgrade-agent`; for a shared agent directory run
390
+ `kiro-cli agent upgrade <dir>`. See <https://kiro.dev/docs/cli/v3/>. The probes never start a
391
+ chat, so they use no Kiro credits, and a reminder never fails a sync. Set
392
+ `STEERSYNC_NO_V3_REMINDER=1` to silence the session hook reminder.
393
+
332
394
  **MCP server.** `steersync init` registers the server in `.kiro/settings/mcp.json`
333
- (`steersync mcp-config` prints the fragment). The server tells the agent which tool answers
395
+ (`steersync mcp-config` prints the fragment). It runs through
396
+ `uvx --from "steersync[mcp]==<version>" steersync mcp`, so nothing needs installing, and it
397
+ auto approves only the read only tools. The server is built on the MCP Python SDK v2
398
+ (`MCPServer`, specification 2026-07-28): tools return structured JSON and carry titles and
399
+ read only, destructive and idempotent hints. A forced pull needs `confirm: true` because it
400
+ overwrites local edits. The server tells the agent which tool answers
334
401
  which request, so plain sentences work:
335
402
 
336
403
  | Say | Tool |
@@ -341,6 +408,7 @@ which request, so plain sentences work:
341
408
  | "what changed", "status", "any open proposals for this repo" | `diff_kiro_config` |
342
409
  | "validate / lint / check the kiro config, agents, hooks, skills" | `validate_kiro_config` |
343
410
  | "what is synced and where" | `list_kiro_collections` |
411
+ | "am I on Kiro V3", "do my agents need upgrading" | `kiro_v3_status` |
344
412
 
345
413
  Every tool accepts a `collections` list. Kiro does not pass the shell's `PATH`,
346
414
  `SSH_AUTH_SOCK`, proxy variables or `GITLAB_TOKEN` to MCP servers, so the rendered entry
@@ -1,38 +1,10 @@
1
- Metadata-Version: 2.5
2
- Name: steersync
3
- Version: 0.3.0
4
- Summary: Sync Kiro steering documents between developer machines and a central git repository.
5
- Project-URL: Homepage, https://github.com/SCGIS-Wales/steersync
6
- Project-URL: Repository, https://github.com/SCGIS-Wales/steersync
7
- Project-URL: Issues, https://github.com/SCGIS-Wales/steersync/issues
8
- Project-URL: Changelog, https://github.com/SCGIS-Wales/steersync/blob/main/CHANGELOG.md
9
- Author-email: Dejan Gregor <dejan.gregor@gmail.com>
10
- License-Expression: Apache-2.0
11
- License-File: LICENSE
12
- Keywords: developer-experience,git,kiro,mcp,pre-push,steering
13
- Classifier: Development Status :: 4 - Beta
14
- Classifier: Environment :: Console
15
- Classifier: Intended Audience :: Developers
16
- Classifier: Operating System :: OS Independent
17
- Classifier: Programming Language :: Python :: 3
18
- Classifier: Programming Language :: Python :: 3 :: Only
19
- Classifier: Programming Language :: Python :: 3.14
20
- Classifier: Topic :: Software Development :: Version Control :: Git
21
- Classifier: Typing :: Typed
22
- Requires-Python: >=3.14
23
- Requires-Dist: click<9,>=8.5
24
- Requires-Dist: pydantic<3,>=2.14
25
- Requires-Dist: pymarkdownlnt<1,>=0.9.40
26
- Requires-Dist: python-frontmatter<2,>=1.3
27
- Requires-Dist: pyyaml<7,>=6.0.3
28
- Provides-Extra: mcp
29
- Requires-Dist: mcp<3,>=2.3; extra == 'mcp'
30
- Description-Content-Type: text/markdown
31
-
32
1
  # steersync
33
2
 
34
- Sync the whole [Kiro](https://kiro.dev) `.kiro/` configuration, steering, specs, skills,
35
- agents, hooks and settings, between developer machines and a central git repository. A plain
3
+ Sync the whole [Kiro](https://kiro.dev) `.kiro/` configuration (steering, specs, skills,
4
+ agents, hooks, settings, the sandbox policy, workflow recipes, prompts, `AGENTS.md` and
5
+ `.kiroignore` files) between developer machines and a central git repository. It targets Kiro
6
+ IDE 1.5 and Kiro CLI 3.5 with the V3 agent harness, and reminds you when a machine is still
7
+ on V2. A plain
36
8
  Python CLI runs from a git pre-push hook and shells out to the `git` binary, so your existing
37
9
  SSH agent or credential helper does the authentication. An MCP server and Kiro session hooks
38
10
  are optional layers on top of the same core.
@@ -55,23 +27,33 @@ layout; each one is configurable and new ones are added with a single YAML block
55
27
  | Collection | Workspace | Global (`~/.kiro`) | Central directory | Files | Lint profile |
56
28
  |---|---|---|---|---|---|
57
29
  | `steering` | `.kiro/steering` | `steering` | `steering/` | `**/*.md` | `steering`: Kiro front matter, references, secrets, markdown |
58
- | `specs` | `.kiro/specs` | none | `specs/` | `**/*.md` | `markdown`: secrets and markdown style |
30
+ | `specs` | `.kiro/specs` | none | `specs/` | every file in each spec (`requirements.md` or `bugfix.md`, `design.md`, `tasks.md`, metadata) | `markdown`: secrets and markdown style |
59
31
  | `skills` | `.kiro/skills` | `skills` | `skills/` | everything (`SKILL.md`, `scripts/`, `references/`, `assets/`) | `skill`: `SKILL.md` needs `name` and `description`, secrets in scripts |
60
- | `agents` | `.kiro/agents` | `agents` | `agents/` | `**/*.json`, `**/*.md` | `agent`: valid JSON with a `name`, flags deprecated `toolsSettings` |
61
- | `hooks` | `.kiro/hooks` | `hooks` | `hooks/` | `**/*.json` | `hooks`: `version`, `hooks[]` with `name`, `trigger`, `action` |
62
- | `settings` | `.kiro/settings` | none | `settings/` | `lsp.json`, `mcp.json` | `settings`: valid JSON, `mcpServers` and `languages` shapes, machine paths |
32
+ | `agents` | `.kiro/agents` | `agents` | `agents/` | `**/*.json`, `**/*.md` (not the `*.json.bak` upgrade backups) | `agent`: V3 universal format, `permissions.rules`, tool names, resources, inline hooks |
33
+ | `hooks` | `.kiro/hooks` | `hooks` | `hooks/` | `**/*.json`, legacy `**/*.kiro.hook` | `hooks`: `version: v1`, triggers, actions, timeouts, `confirm` |
34
+ | `settings` | `.kiro/settings` | none | `settings/` | `lsp.json`, `mcp.json` | `settings`: shapes, literal secrets, OAuth, machine paths |
35
+ | `sandbox` | `.kiro/settings` | none | `sandbox/` | `sandbox.json` | `settings`: `enabled`, `networkAccess` |
36
+ | `cli-settings` (off by default) | `.kiro/settings` | none | `cli-settings/` | `cli.json` | `settings`: rejects global only keys such as `chat.agentEngine` |
37
+ | `workflows` | `.kiro/workflows` | `workflows` | `workflows/` | `**/*.workflow.json`, `.yaml`, `.yml` | `workflow`: the recipe schema of Kiro CLI 3.5 |
63
38
  | `prompts` | `.kiro/prompts` | `prompts` | `prompts/` | `**/*.md` | `prompt`: markdown plus the 50 character name limit |
64
- | `agents-md` | `AGENTS.md` at the root | none | `agents-md/` | `AGENTS.md` | `markdown` (kept in the project repository too) |
65
-
66
- Execute bits on skill scripts survive the round trip, hidden files are never synced, and
67
- files a collection's patterns do not select are never touched on either side. Limit any
39
+ | `agents-md` | the repository | none | `agents-md/` | `**/AGENTS.md` (root and nested) | `markdown` (kept in the project repository too) |
40
+ | `kiroignore` | the repository | `settings` (`kiroignore`) | `kiroignore/` | `**/.kiroignore` | `kiroignore`: gitignore syntax, advice on `.env*` and `*.pem` |
41
+
42
+ Execute bits on skill scripts survive the round trip. Hidden directories are never synced,
43
+ and a hidden file only when a pattern names it (`**/.kiroignore`). Files a collection's
44
+ patterns do not select are never touched on either side, which is why `settings`, `sandbox`
45
+ and `cli-settings` can share `.kiro/settings`. The repository wide collections skip
46
+ `node_modules`, virtual environments, `dist`, `build` and `target` without walking them. Limit any
68
47
  command to some collections with `--collection NAME` (repeatable), list them with
69
48
  `steersync config collections`, and see [docs/central-layout.md](docs/central-layout.md) for
70
49
  a worked example of a full `.kiro/` tree in the central repository.
71
50
 
72
- Not synced on purpose: `~/.kiro/powers/` (installed by Kiro from a registry, not authored),
73
- `~/.kiro/settings/cli.json` and `permissions.yaml` (per user, outside any repository) and
74
- knowledge bases (declared in agent resources, indexed by Kiro). Every path above comes from
51
+ Never synced, by design: workspace permissions (`~/.kiro/workspace-roots/<hash>/permissions.yaml`,
52
+ kept per user so that a cloned repository cannot inject permission rules) and
53
+ `~/.kiro/settings/permissions.yaml`, `~/.kiro/powers/` (installed from a registry),
54
+ `~/.kiro/memories/`, `~/.kiro/sessions/`, `~/.kiro/crew/`, `~/.kiro/settings/cli.json`,
55
+ `managed-settings.json` and knowledge base indexes (the declarations in agent `resources`
56
+ are synced with the agent). Every path above comes from
75
57
  the Kiro configuration scopes documentation; a new kind of content is one YAML block.
76
58
 
77
59
  ## Install
@@ -81,8 +63,11 @@ Requires Python 3.14 or newer and git 2.18 or newer. Every
81
63
  sdist and a `SHA256SUMS` file, with signed build provenance.
82
64
 
83
65
  ```bash
84
- VERSION=0.3.0
66
+ VERSION=0.4.0
85
67
  uv tool install "https://github.com/SCGIS-Wales/steersync/releases/download/v${VERSION}/steersync-${VERSION}-py3-none-any.whl"
68
+ # or run it without installing
69
+ uvx steersync --help
70
+ uvx --from "steersync[mcp]" steersync-mcp
86
71
  # with the MCP server
87
72
  uv tool install "steersync[mcp] @ https://github.com/SCGIS-Wales/steersync/releases/download/v${VERSION}/steersync-${VERSION}-py3-none-any.whl"
88
73
  # verify where the wheel came from
@@ -182,10 +167,12 @@ subdirectory; `pull` and `status` print a warning pointing at them until that is
182
167
  | `steersync init [--write-config] [--hook] [--no-exclude] [--no-kiro] [--mcp-command PATH]` | Prepare a repository: excludes, git hook, Kiro session hook and MCP server entry. |
183
168
  | `steersync install-hook [--force]` | Install or update the chaining pre-push hook. |
184
169
  | `steersync kiro-hook [--engine v2\|v3] [--write]` | Render a Kiro hook that runs `steersync pull --quiet` at session start. |
185
- | `steersync mcp-config [--remote URL]` | Render an `mcp.json` fragment. |
186
- | `steersync mcp` | Run the MCP stdio server. |
170
+ | `steersync migrate-hooks [--write]` | Convert `*.kiro.hook` files and CLI 2.x inline agent hooks into `.kiro/hooks/*.json`. Dry run by default; never overwrites or deletes. |
171
+ | `steersync v3-status [--json] [--strict]` | Report the kiro-cli version, `chat.agentEngine` and agents still in the V2 format. `--strict` exits 10 when a reminder applies. |
172
+ | `steersync mcp-config [--command uvx] [--remote URL]` | Render an `mcp.json` fragment. |
173
+ | `steersync mcp` (or `steersync-mcp`) | Run the MCP stdio server. |
187
174
  | `steersync config show\|validate\|default\|collections` | Inspect configuration and the resolved collection directories. |
188
- | `steersync doctor` | Report git version, resolved paths, remote and project slug. |
175
+ | `steersync doctor` | Report git version, resolved paths, remote, project slug and the Kiro CLI harness. |
189
176
 
190
177
  Global options: `--config PATH`, `--log-level`, `--log-format text|json`, `--quiet`.
191
178
 
@@ -290,7 +277,7 @@ Teams that already use [pre-commit](https://pre-commit.com) can use the publishe
290
277
  default_install_hook_types: [pre-commit, pre-push]
291
278
  repos:
292
279
  - repo: https://github.com/SCGIS-Wales/steersync
293
- rev: v0.3.0
280
+ rev: v0.4.0
294
281
  hooks:
295
282
  - id: steersync-push
296
283
  - id: steersync-lint
@@ -338,9 +325,12 @@ The merge request is opened in two ways:
338
325
  ## Validation
339
326
 
340
327
  Each collection runs one lint profile: `steering`, `agent`, `hooks`, `skill`, `settings`,
341
- `prompt`, `markdown`, `json` or `generic`. **Errors** are things Kiro cannot read (front
342
- matter after a blank line, an unknown inclusion mode, invalid JSON, a `SKILL.md` without
343
- `name` and `description`) or secrets; they stop a push. **Warnings** are best practices from
328
+ `prompt`, `workflow`, `kiroignore`, `markdown`, `json` or `generic`. **Errors** are things
329
+ Kiro cannot read or would rewrite (front matter after a blank line, an unknown inclusion
330
+ mode, invalid JSON, a `SKILL.md` without `name` and `description`, a hook without
331
+ `version: "v1"`, a workflow `repeat` without `maxIterations`, an unknown sandbox
332
+ `networkAccess`, a V2 format agent) or secrets, including literal tokens in `mcp.json`
333
+ `env`, `headers` and `oauth.clientSecret`; they stop a push. **Warnings** are best practices from
344
334
  the Kiro documentation, reported objectively and never blocking: a steering file with a
345
335
  numeric prefix, an `auto` description that is not written as a trigger, a `globs` key where
346
336
  Kiro reads `fileMatchPattern`, an agent with `tools: ["*"]` or a `file://.kiro/steering/**`
@@ -360,8 +350,22 @@ and `lint.practices: false` turns the warnings off.
360
350
  fire only in headless runs or with a custom agent active, so treat them as a convenience and
361
351
  keep the git hook as the dependable trigger.
362
352
 
353
+ **Kiro CLI V3.** Kiro CLI 3.0.0 made V3 the default agent harness; V2 still runs but gets no
354
+ new features. `steersync doctor`, `steersync v3-status`, the `kiro_v3_status` MCP tool and
355
+ the session hook (at most once a day) check `kiro-cli --version`, `chat.agentEngine` and your
356
+ agent files. When a reminder applies, run `kiro-cli settings chat.agentEngine v3`, start
357
+ `kiro-cli` and run `/upgrade-agent`; for a shared agent directory run
358
+ `kiro-cli agent upgrade <dir>`. See <https://kiro.dev/docs/cli/v3/>. The probes never start a
359
+ chat, so they use no Kiro credits, and a reminder never fails a sync. Set
360
+ `STEERSYNC_NO_V3_REMINDER=1` to silence the session hook reminder.
361
+
363
362
  **MCP server.** `steersync init` registers the server in `.kiro/settings/mcp.json`
364
- (`steersync mcp-config` prints the fragment). The server tells the agent which tool answers
363
+ (`steersync mcp-config` prints the fragment). It runs through
364
+ `uvx --from "steersync[mcp]==<version>" steersync mcp`, so nothing needs installing, and it
365
+ auto approves only the read only tools. The server is built on the MCP Python SDK v2
366
+ (`MCPServer`, specification 2026-07-28): tools return structured JSON and carry titles and
367
+ read only, destructive and idempotent hints. A forced pull needs `confirm: true` because it
368
+ overwrites local edits. The server tells the agent which tool answers
365
369
  which request, so plain sentences work:
366
370
 
367
371
  | Say | Tool |
@@ -372,6 +376,7 @@ which request, so plain sentences work:
372
376
  | "what changed", "status", "any open proposals for this repo" | `diff_kiro_config` |
373
377
  | "validate / lint / check the kiro config, agents, hooks, skills" | `validate_kiro_config` |
374
378
  | "what is synced and where" | `list_kiro_collections` |
379
+ | "am I on Kiro V3", "do my agents need upgrading" | `kiro_v3_status` |
375
380
 
376
381
  Every tool accepts a `collections` list. Kiro does not pass the shell's `PATH`,
377
382
  `SSH_AUTH_SOCK`, proxy variables or `GITLAB_TOKEN` to MCP servers, so the rendered entry
@@ -1,17 +1,20 @@
1
1
  [build-system]
2
- requires = ["hatchling>=1.32,<2"]
2
+ requires = ["hatchling>=1.33,<2"]
3
3
  build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "steersync"
7
7
  dynamic = ["version"]
8
- description = "Sync Kiro steering documents between developer machines and a central git repository."
8
+ description = "Sync Kiro configuration (steering, specs, skills, agents, hooks, workflows, settings) with a central git repository."
9
9
  readme = "README.md"
10
10
  license = "Apache-2.0"
11
11
  license-files = ["LICENSE"]
12
12
  requires-python = ">=3.14"
13
13
  authors = [{ name = "Dejan Gregor", email = "dejan.gregor@gmail.com" }]
14
- keywords = ["kiro", "steering", "git", "pre-push", "mcp", "developer-experience"]
14
+ keywords = [
15
+ "kiro", "kiro-cli", "steering", "agents", "hooks", "workflows", "git", "pre-push", "mcp",
16
+ "developer-experience",
17
+ ]
15
18
  classifiers = [
16
19
  "Development Status :: 4 - Beta",
17
20
  "Environment :: Console",
@@ -20,15 +23,16 @@ classifiers = [
20
23
  "Programming Language :: Python :: 3",
21
24
  "Programming Language :: Python :: 3 :: Only",
22
25
  "Programming Language :: Python :: 3.14",
26
+ "Programming Language :: Python :: 3.15",
23
27
  "Topic :: Software Development :: Version Control :: Git",
24
28
  "Typing :: Typed",
25
29
  ]
26
30
  dependencies = [
27
- "click>=8.5,<9",
28
- "pydantic>=2.14,<3",
31
+ "click>=8.5.1,<9",
32
+ "pydantic>=2.14.4,<3",
29
33
  "python-frontmatter>=1.3,<2",
30
- "PyYAML>=6.0.3,<7",
31
- "pymarkdownlnt>=0.9.40,<1",
34
+ "PyYAML>=6.0.4,<7",
35
+ "pymarkdownlnt>=0.9.42,<1",
32
36
  ]
33
37
 
34
38
  [project.optional-dependencies]
@@ -36,6 +40,7 @@ mcp = ["mcp>=2.3,<3"]
36
40
 
37
41
  [project.scripts]
38
42
  steersync = "steersync.cli:run"
43
+ steersync-mcp = "steersync.mcp_server:main"
39
44
 
40
45
  [project.urls]
41
46
  Homepage = "https://github.com/SCGIS-Wales/steersync"
@@ -45,13 +50,13 @@ Changelog = "https://github.com/SCGIS-Wales/steersync/blob/main/CHANGELOG.md"
45
50
 
46
51
  [dependency-groups]
47
52
  dev = [
48
- "pytest>=9.1,<10",
53
+ "pytest>=9.2,<10",
49
54
  "pytest-cov>=7.1,<8",
50
- "ruff>=0.17,<1",
55
+ "ruff>=0.17.6,<1",
51
56
  "mypy>=2.4,<3",
52
57
  "types-PyYAML>=6.0.12",
53
- "bandit[toml]>=1.8,<2",
54
- "pip-audit>=2.9,<3",
58
+ "bandit[toml]>=1.9,<2",
59
+ "pip-audit>=2.10,<3",
55
60
  "mcp>=2.3,<3",
56
61
  ]
57
62
 
@@ -108,9 +113,10 @@ files = ["src", "tests", "scripts"]
108
113
  module = ["frontmatter", "frontmatter.*", "pymarkdown.*", "mcp.*"]
109
114
  ignore_missing_imports = true
110
115
 
111
- [tool.pytest.ini_options]
116
+ [tool.pytest]
117
+ # pytest 9 native TOML configuration.
112
118
  testpaths = ["tests"]
113
- addopts = "-ra --strict-markers --strict-config"
119
+ addopts = ["-ra", "--strict-markers", "--strict-config"]
114
120
  xfail_strict = true
115
121
  filterwarnings = ["error"]
116
122
 
@@ -120,7 +126,7 @@ source = ["steersync"]
120
126
  omit = ["src/steersync/__main__.py"]
121
127
 
122
128
  [tool.coverage.report]
123
- fail_under = 85
129
+ fail_under = 90
124
130
  show_missing = true
125
131
  skip_covered = false
126
132
  exclude_also = ["if TYPE_CHECKING:", "raise NotImplementedError"]
@@ -18,8 +18,6 @@ Used by the CI workflow on every push to ``main``. The decision is deterministic
18
18
  Every function is pure apart from ``apply`` so the rules are unit tested.
19
19
  """
20
20
 
21
- from __future__ import annotations
22
-
23
21
  import argparse
24
22
  import datetime as dt
25
23
  import re
@@ -1,5 +1,5 @@
1
1
  """steersync: sync Kiro steering documents with a central git repository."""
2
2
 
3
- __version__ = "0.3.0"
3
+ __version__ = "0.4.0"
4
4
 
5
5
  __all__ = ["__version__"]