steersync 0.2.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.
- {steersync-0.2.0 → steersync-0.4.0}/CHANGELOG.md +96 -0
- {steersync-0.2.0 → steersync-0.4.0}/PKG-INFO +167 -65
- {steersync-0.2.0 → steersync-0.4.0}/README.md +159 -58
- {steersync-0.2.0 → steersync-0.4.0}/pyproject.toml +23 -16
- steersync-0.4.0/scripts/prepare_release.py +226 -0
- {steersync-0.2.0 → steersync-0.4.0}/src/steersync/__init__.py +1 -1
- {steersync-0.2.0 → steersync-0.4.0}/src/steersync/cli.py +277 -11
- {steersync-0.2.0 → steersync-0.4.0}/src/steersync/config.py +136 -9
- {steersync-0.2.0 → steersync-0.4.0}/src/steersync/errors.py +6 -0
- steersync-0.4.0/src/steersync/gitlab.py +209 -0
- {steersync-0.2.0 → steersync-0.4.0}/src/steersync/gitops.py +64 -9
- {steersync-0.2.0 → steersync-0.4.0}/src/steersync/hooks.py +111 -20
- steersync-0.4.0/src/steersync/kiro_rules.py +819 -0
- steersync-0.4.0/src/steersync/kiro_version.py +269 -0
- {steersync-0.2.0 → steersync-0.4.0}/src/steersync/lint.py +242 -118
- {steersync-0.2.0 → steersync-0.4.0}/src/steersync/locking.py +2 -4
- {steersync-0.2.0 → steersync-0.4.0}/src/steersync/logging_utils.py +0 -2
- steersync-0.4.0/src/steersync/mcp_server.py +394 -0
- steersync-0.4.0/src/steersync/migrate.py +175 -0
- {steersync-0.2.0 → steersync-0.4.0}/src/steersync/paths.py +0 -2
- steersync-0.4.0/src/steersync/practices.py +522 -0
- steersync-0.4.0/src/steersync/resources/default_config.yaml +262 -0
- {steersync-0.2.0 → steersync-0.4.0}/src/steersync/steering.py +32 -7
- {steersync-0.2.0 → steersync-0.4.0}/src/steersync/sync.py +205 -16
- {steersync-0.2.0 → steersync-0.4.0}/steersync.example.yaml +16 -2
- {steersync-0.2.0 → steersync-0.4.0}/tests/conftest.py +7 -2
- steersync-0.4.0/tests/test_automation.py +491 -0
- {steersync-0.2.0 → steersync-0.4.0}/tests/test_cli.py +17 -7
- {steersync-0.2.0 → steersync-0.4.0}/tests/test_collections.py +49 -11
- {steersync-0.2.0 → steersync-0.4.0}/tests/test_config.py +7 -2
- steersync-0.4.0/tests/test_gitlab.py +188 -0
- {steersync-0.2.0 → steersync-0.4.0}/tests/test_gitops.py +20 -8
- {steersync-0.2.0 → steersync-0.4.0}/tests/test_hardening.py +4 -6
- {steersync-0.2.0 → steersync-0.4.0}/tests/test_hooks.py +27 -4
- steersync-0.4.0/tests/test_kiro_collections.py +156 -0
- steersync-0.4.0/tests/test_kiro_rules.py +341 -0
- steersync-0.4.0/tests/test_kiro_version.py +187 -0
- {steersync-0.2.0 → steersync-0.4.0}/tests/test_lint.py +14 -6
- steersync-0.4.0/tests/test_mcp_server.py +89 -0
- steersync-0.4.0/tests/test_migrate.py +111 -0
- steersync-0.4.0/tests/test_practices.py +213 -0
- steersync-0.4.0/tests/test_prepare_release.py +158 -0
- {steersync-0.2.0 → steersync-0.4.0}/tests/test_steering.py +0 -2
- {steersync-0.2.0 → steersync-0.4.0}/tests/test_sync.py +21 -6
- steersync-0.2.0/src/steersync/mcp_server.py +0 -171
- steersync-0.2.0/src/steersync/resources/default_config.yaml +0 -154
- steersync-0.2.0/tests/test_mcp_server.py +0 -58
- {steersync-0.2.0 → steersync-0.4.0}/.gitignore +0 -0
- {steersync-0.2.0 → steersync-0.4.0}/LICENSE +0 -0
- {steersync-0.2.0 → steersync-0.4.0}/src/steersync/__main__.py +0 -0
- {steersync-0.2.0 → steersync-0.4.0}/tests/__init__.py +0 -0
|
@@ -5,6 +5,102 @@ 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
|
+
|
|
58
|
+
## [0.3.0] - 2026-10-13
|
|
59
|
+
|
|
60
|
+
### Added
|
|
61
|
+
|
|
62
|
+
- Two more collections from the Kiro configuration scopes: `prompts` (`.kiro/prompts` and
|
|
63
|
+
`~/.kiro/prompts`, the saved prompts that become slash commands) and `agents-md` (the
|
|
64
|
+
`AGENTS.md` at the repository root). Legacy `.kiro.hook` files are picked up by the hooks
|
|
65
|
+
collection and flagged.
|
|
66
|
+
- Best practice validation. Every collection profile now reports warnings taken from the Kiro
|
|
67
|
+
documentation (steering file naming and `auto` descriptions, the `globs` key, always on
|
|
68
|
+
context budget, missing foundation files, agent tool wildcards and startup globs, inline
|
|
69
|
+
agent hooks on CLI 3.0, hook timeouts and legacy schemas, skill name and description
|
|
70
|
+
limits, machine specific paths in `mcp.json`, prompt name length) plus the `settings` and
|
|
71
|
+
`prompt` profiles. Warnings never block; thresholds live under `lint.practice_limits` and
|
|
72
|
+
`lint.practices: false` turns them off. The rules are listed in `docs/validation.md`.
|
|
73
|
+
- `steersync init` writes the Kiro `SessionStart` hook and registers the steersync MCP server
|
|
74
|
+
in `.kiro/settings/mcp.json` (other servers kept, an existing entry left alone), so a Kiro
|
|
75
|
+
session in any repository refreshes and loads the configuration without being asked.
|
|
76
|
+
`steersync lint` warns when either piece is missing.
|
|
77
|
+
- GitLab merge requests through the REST API: `steersync mr` and the `raise_merge_request`
|
|
78
|
+
MCP tool open or find the merge request for the proposal branch, `push` confirms or creates
|
|
79
|
+
it and prints the URL when the token is present. The token comes from `GITLAB_TOKEN` (name
|
|
80
|
+
configurable with `gitlab.token_env`); `gitlab.api_url`, `gitlab.project` and
|
|
81
|
+
`gitlab.target_branch` are derived from `remote.url` and `remote.default_branch` unless set.
|
|
82
|
+
- `push` and `status` list other proposal branches of the same project still on the central
|
|
83
|
+
remote and warn about them (`branch.warn_existing`).
|
|
84
|
+
- Offline fallback: when the central repository is unreachable and a cache clone exists,
|
|
85
|
+
`pull` and `status` apply the cached default branch and say so (`sync.offline_fallback`).
|
|
86
|
+
`pull --best-effort` runs with the hook time budget.
|
|
87
|
+
- Automatic releases: merging a pull request to `main` computes the version from a
|
|
88
|
+
`release:*` label, a Conventional Commits title prefix or the Unreleased changelog section,
|
|
89
|
+
commits the changelog and version bump, publishes to PyPI and creates the tag and GitHub
|
|
90
|
+
release in the same run (`scripts/prepare_release.py`).
|
|
91
|
+
|
|
92
|
+
### Changed
|
|
93
|
+
|
|
94
|
+
- Proposal branches are named `kiro-config/{project}/{user}-{hash}`; `{user}` now prefers the
|
|
95
|
+
operating system user name (letters, digits and dashes), then the git email, then the git
|
|
96
|
+
name (`branch.user_from`). The template must keep `{project}` and `{hash}`.
|
|
97
|
+
- MCP tools are named by intent and described for the agent: `pull_kiro_config`,
|
|
98
|
+
`push_kiro_config`, `raise_merge_request`, `diff_kiro_config`, `validate_kiro_config` and
|
|
99
|
+
`list_kiro_collections` replace `pull_steering`, `push_steering`, `diff_steering` and
|
|
100
|
+
`lint_steering`. The rendered `mcp.json` entry forwards the GitLab token variable.
|
|
101
|
+
- `pull` logs the central content's lint errors and a one line count of warnings instead of
|
|
102
|
+
every warning.
|
|
103
|
+
|
|
8
104
|
## [0.2.0] - 2026-10-12
|
|
9
105
|
|
|
10
106
|
### Added
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: steersync
|
|
3
|
-
Version: 0.
|
|
4
|
-
Summary: Sync Kiro steering
|
|
3
|
+
Version: 0.4.0
|
|
4
|
+
Summary: Sync Kiro configuration (steering, specs, skills, agents, hooks, workflows, settings) with a central git repository.
|
|
5
5
|
Project-URL: Homepage, https://github.com/SCGIS-Wales/steersync
|
|
6
6
|
Project-URL: Repository, https://github.com/SCGIS-Wales/steersync
|
|
7
7
|
Project-URL: Issues, https://github.com/SCGIS-Wales/steersync/issues
|
|
@@ -9,7 +9,7 @@ Project-URL: Changelog, https://github.com/SCGIS-Wales/steersync/blob/main/CHANG
|
|
|
9
9
|
Author-email: Dejan Gregor <dejan.gregor@gmail.com>
|
|
10
10
|
License-Expression: Apache-2.0
|
|
11
11
|
License-File: LICENSE
|
|
12
|
-
Keywords: developer-experience,git,kiro,mcp,pre-push,steering
|
|
12
|
+
Keywords: agents,developer-experience,git,hooks,kiro,kiro-cli,mcp,pre-push,steering,workflows
|
|
13
13
|
Classifier: Development Status :: 4 - Beta
|
|
14
14
|
Classifier: Environment :: Console
|
|
15
15
|
Classifier: Intended Audience :: Developers
|
|
@@ -17,22 +17,26 @@ Classifier: Operating System :: OS Independent
|
|
|
17
17
|
Classifier: Programming Language :: Python :: 3
|
|
18
18
|
Classifier: Programming Language :: Python :: 3 :: Only
|
|
19
19
|
Classifier: Programming Language :: Python :: 3.14
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
20
21
|
Classifier: Topic :: Software Development :: Version Control :: Git
|
|
21
22
|
Classifier: Typing :: Typed
|
|
22
23
|
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.
|
|
24
|
+
Requires-Dist: click<9,>=8.5.1
|
|
25
|
+
Requires-Dist: pydantic<3,>=2.14.4
|
|
26
|
+
Requires-Dist: pymarkdownlnt<1,>=0.9.42
|
|
26
27
|
Requires-Dist: python-frontmatter<2,>=1.3
|
|
27
|
-
Requires-Dist: pyyaml<7,>=6.0.
|
|
28
|
+
Requires-Dist: pyyaml<7,>=6.0.4
|
|
28
29
|
Provides-Extra: mcp
|
|
29
30
|
Requires-Dist: mcp<3,>=2.3; extra == 'mcp'
|
|
30
31
|
Description-Content-Type: text/markdown
|
|
31
32
|
|
|
32
33
|
# steersync
|
|
33
34
|
|
|
34
|
-
Sync the whole [Kiro](https://kiro.dev) `.kiro/` configuration
|
|
35
|
-
agents, hooks
|
|
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
|
|
36
40
|
Python CLI runs from a git pre-push hook and shells out to the `git` binary, so your existing
|
|
37
41
|
SSH agent or credential helper does the authentication. An MCP server and Kiro session hooks
|
|
38
42
|
are optional layers on top of the same core.
|
|
@@ -55,18 +59,35 @@ layout; each one is configurable and new ones are added with a single YAML block
|
|
|
55
59
|
| Collection | Workspace | Global (`~/.kiro`) | Central directory | Files | Lint profile |
|
|
56
60
|
|---|---|---|---|---|---|
|
|
57
61
|
| `steering` | `.kiro/steering` | `steering` | `steering/` | `**/*.md` | `steering`: Kiro front matter, references, secrets, markdown |
|
|
58
|
-
| `specs` | `.kiro/specs` | none | `specs/` |
|
|
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 |
|
|
59
63
|
| `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`:
|
|
61
|
-
| `hooks` | `.kiro/hooks` | `hooks` | `hooks/` | `**/*.json` | `hooks`: `version`,
|
|
62
|
-
| `settings` | `.kiro/settings` | none | `settings/` | `lsp.json`, `mcp.json` | `
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
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 |
|
|
70
|
+
| `prompts` | `.kiro/prompts` | `prompts` | `prompts/` | `**/*.md` | `prompt`: markdown plus the 50 character name limit |
|
|
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
|
|
66
79
|
command to some collections with `--collection NAME` (repeatable), list them with
|
|
67
80
|
`steersync config collections`, and see [docs/central-layout.md](docs/central-layout.md) for
|
|
68
81
|
a worked example of a full `.kiro/` tree in the central repository.
|
|
69
82
|
|
|
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
|
|
89
|
+
the Kiro configuration scopes documentation; a new kind of content is one YAML block.
|
|
90
|
+
|
|
70
91
|
## Install
|
|
71
92
|
|
|
72
93
|
Requires Python 3.14 or newer and git 2.18 or newer. Every
|
|
@@ -74,8 +95,11 @@ Requires Python 3.14 or newer and git 2.18 or newer. Every
|
|
|
74
95
|
sdist and a `SHA256SUMS` file, with signed build provenance.
|
|
75
96
|
|
|
76
97
|
```bash
|
|
77
|
-
VERSION=0.
|
|
98
|
+
VERSION=0.4.0
|
|
78
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
|
|
79
103
|
# with the MCP server
|
|
80
104
|
uv tool install "steersync[mcp] @ https://github.com/SCGIS-Wales/steersync/releases/download/v${VERSION}/steersync-${VERSION}-py3-none-any.whl"
|
|
81
105
|
# verify where the wheel came from
|
|
@@ -103,7 +127,9 @@ files that the GitHub release carries.
|
|
|
103
127
|
2. Prepare a project. This adds every synced directory (`.kiro/steering/`, `.kiro/specs/`,
|
|
104
128
|
`.kiro/skills/`, ...) and the lock file to `.git/info/exclude` (so centrally managed
|
|
105
129
|
content is never committed to the project by accident; set `git_exclude: false` on a
|
|
106
|
-
collection to keep committing it)
|
|
130
|
+
collection to keep committing it), installs a chaining pre-push hook, writes the Kiro
|
|
131
|
+
`SessionStart` hook that pulls at every session start and registers the steersync MCP
|
|
132
|
+
server in `.kiro/settings/mcp.json`:
|
|
107
133
|
|
|
108
134
|
```bash
|
|
109
135
|
cd ~/code/my-service
|
|
@@ -113,9 +139,28 @@ files that the GitHub release carries.
|
|
|
113
139
|
|
|
114
140
|
3. Edit anything under `.kiro/`. On your next `git push`, or on demand with
|
|
115
141
|
`steersync push`, every collection is proposed to the central repository as one merge
|
|
116
|
-
request.
|
|
142
|
+
request. With `GITLAB_TOKEN` exported, the merge request URL is printed and
|
|
143
|
+
`steersync mr` opens or finds it at any time.
|
|
144
|
+
|
|
145
|
+
Run `steersync doctor` at any time to see what steersync has resolved, and `steersync lint`
|
|
146
|
+
to validate the configuration against Kiro's rules and best practices.
|
|
147
|
+
|
|
148
|
+
## Starting Kiro in any repository
|
|
149
|
+
|
|
150
|
+
The goal is that anyone who clones a project and starts Kiro gets the whole configuration
|
|
151
|
+
without asking for it. `steersync init` makes that true for a repository:
|
|
152
|
+
|
|
153
|
+
| Piece | What it does | Written by |
|
|
154
|
+
|---|---|---|
|
|
155
|
+
| `.kiro/hooks/steersync.json` | A V3 `SessionStart` hook running `steersync pull --quiet --best-effort`, so the session starts from the latest merged configuration. Bounded git time; never fails the session. | `steersync init` (or `steersync kiro-hook --write`) |
|
|
156
|
+
| `.kiro/settings/mcp.json` | The steersync MCP server, so "pull the kiro config", "push my steering", "raise an MR for the kiro config" or "validate the agents" work in chat. | `steersync init` (merged into an existing file, other servers kept) |
|
|
157
|
+
| `.git/hooks/pre-push` | Proposes `.kiro/` on every push of the project. | `steersync init --hook` |
|
|
117
158
|
|
|
118
|
-
|
|
159
|
+
Kiro then loads what it finds: always on steering in every session, `fileMatch`, `manual`
|
|
160
|
+
and `auto` steering on CLI V3, skills on demand, prompts as slash commands, hooks and
|
|
161
|
+
settings. `steersync lint` warns (`autoload-hook-missing`, `autoload-mcp-missing`) when a
|
|
162
|
+
repository lacks either piece. On CLI 2.x, where standalone hooks do not exist, paste
|
|
163
|
+
`steersync kiro-hook --engine v2` into the custom agent's `hooks` block.
|
|
119
164
|
|
|
120
165
|
## Central repository layout
|
|
121
166
|
|
|
@@ -150,13 +195,16 @@ subdirectory; `pull` and `status` print a warning pointing at them until that is
|
|
|
150
195
|
| `steersync push [--dry-run] [--scope global] [--no-lint] [-m MSG] [-c NAME] [--json]` | Propose local collections centrally in one branch. `--from-hook` is used by git hooks and never blocks the push unless strict. |
|
|
151
196
|
| `steersync status [-c NAME] [--json]` | Show adds, updates, deletes and local edits per collection in both directions. |
|
|
152
197
|
| `steersync lint [PATHS] [-c NAME] [--profile P] [--json]` | Validate every collection with its profile, or explicit paths. Exit code 4 on errors. |
|
|
153
|
-
| `steersync
|
|
198
|
+
| `steersync mr [--branch NAME] [--title T] [-c NAME] [--json]` | Open, or find, the GitLab merge request for the pushed proposal branch. Needs the token in `GITLAB_TOKEN` (configurable). |
|
|
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. |
|
|
154
200
|
| `steersync install-hook [--force]` | Install or update the chaining pre-push hook. |
|
|
155
201
|
| `steersync kiro-hook [--engine v2\|v3] [--write]` | Render a Kiro hook that runs `steersync pull --quiet` at session start. |
|
|
156
|
-
| `steersync
|
|
157
|
-
| `steersync
|
|
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. |
|
|
158
206
|
| `steersync config show\|validate\|default\|collections` | Inspect configuration and the resolved collection directories. |
|
|
159
|
-
| `steersync doctor` | Report git version, resolved paths, remote and
|
|
207
|
+
| `steersync doctor` | Report git version, resolved paths, remote, project slug and the Kiro CLI harness. |
|
|
160
208
|
|
|
161
209
|
Global options: `--config PATH`, `--log-level`, `--log-format text|json`, `--quiet`.
|
|
162
210
|
|
|
@@ -176,6 +224,8 @@ for the packaged defaults.
|
|
|
176
224
|
| `STEERSYNC_GIT_BINARY` | `git.binary` |
|
|
177
225
|
| `STEERSYNC_LOG_LEVEL`, `STEERSYNC_LOG_FORMAT` | `logging.*` |
|
|
178
226
|
| `STEERSYNC_STRICT` | `hook.strict` |
|
|
227
|
+
| `STEERSYNC_GITLAB_API_URL`, `STEERSYNC_GITLAB_PROJECT` | `gitlab.api_url`, `gitlab.project` |
|
|
228
|
+
| `GITLAB_TOKEN` (name set by `gitlab.token_env`) | Token with the `api` scope used only for merge requests |
|
|
179
229
|
| `KIRO_HOME` | Location of `~/.kiro`, as honoured by kiro-cli |
|
|
180
230
|
|
|
181
231
|
Unknown keys, invalid patterns, unsafe paths and malformed push options are rejected at load
|
|
@@ -221,6 +271,8 @@ share a directory on either side.
|
|
|
221
271
|
| A failed push always resets the cache clone to a clean default branch. | automatic |
|
|
222
272
|
| From a pre-push hook each git call is capped and retried at most once, and no failure, including an unexpected bug, blocks the push unless strict mode is on. | `hook.timeout_seconds`, `hook.strict` |
|
|
223
273
|
| Central and local content larger than the limits is refused. | `sync.max_files`, `sync.max_total_bytes` |
|
|
274
|
+
| When the central repository cannot be reached and a cache clone exists, `pull` and `status` apply the cached copy of the default branch and say so (`offline` in JSON output). Permanent errors such as authentication failures still fail, and `push` never uses the cache. | `sync.offline_fallback` |
|
|
275
|
+
| `pull --best-effort` (the Kiro session hook) runs with the hook time budget, so a slow server never stalls a session start. | `hook.timeout_seconds` |
|
|
224
276
|
|
|
225
277
|
## How pull decides what to write
|
|
226
278
|
|
|
@@ -257,7 +309,7 @@ Teams that already use [pre-commit](https://pre-commit.com) can use the publishe
|
|
|
257
309
|
default_install_hook_types: [pre-commit, pre-push]
|
|
258
310
|
repos:
|
|
259
311
|
- repo: https://github.com/SCGIS-Wales/steersync
|
|
260
|
-
rev: v0.
|
|
312
|
+
rev: v0.4.0
|
|
261
313
|
hooks:
|
|
262
314
|
- id: steersync-push
|
|
263
315
|
- id: steersync-lint
|
|
@@ -266,52 +318,102 @@ repos:
|
|
|
266
318
|
The lint hook receives the changed files under `.kiro/` and lints each with the profile of
|
|
267
319
|
the collection it belongs to.
|
|
268
320
|
|
|
269
|
-
## GitLab merge requests
|
|
270
|
-
|
|
271
|
-
The default push options create a merge request against the default branch, remove the source
|
|
272
|
-
branch on merge and set a title. Branch names follow `steering/{project}/{user}-{hash}`, where
|
|
273
|
-
the hash covers every file, so two people proposing identical content share one branch and a
|
|
274
|
-
second identical push is reported as `already-proposed`. Servers that do not advertise push
|
|
275
|
-
options (GitHub, plain bare repositories) make git fail, so steersync retries once without them
|
|
276
|
-
and says so. Push options may use `{default_branch}`, `{project}`, `{user}` and `{hash}`.
|
|
321
|
+
## Proposal branches and GitLab merge requests
|
|
277
322
|
|
|
278
|
-
|
|
323
|
+
Pulls always come from the central repository's default branch (`remote.default_branch`,
|
|
324
|
+
`main` unless configured). Pushes go to a proposal branch named after the project repository
|
|
325
|
+
you are working in:
|
|
279
326
|
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
`hooks` adds `hook-schema`, `hook-trigger` and `hook-action`, `agent` adds `agent-schema`,
|
|
285
|
-
`agent-name` and `agent-deprecated-key`, and `generic` only enforces the size limit and secret
|
|
286
|
-
scanning, allowing binary assets. New profiles are one function in `steersync.lint.PROFILES`.
|
|
327
|
+
```text
|
|
328
|
+
kiro-config/{project}/{user}-{hash}
|
|
329
|
+
kiro-config/acme/platform/entra-app-registration/dgregor-3f9a1c2e
|
|
330
|
+
```
|
|
287
331
|
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
332
|
+
`{project}` is the slug of the project's origin URL, `{user}` comes from the sources listed
|
|
333
|
+
in `branch.user_from` (the operating system user name first, reduced to letters, digits and
|
|
334
|
+
dashes, then the local part of the git `user.email`, then the git `user.name`) and `{hash}`
|
|
335
|
+
covers every synced file, so two people proposing identical content share one branch and a
|
|
336
|
+
second identical push is reported as `already-proposed`. The template is configurable; it
|
|
337
|
+
must keep `{project}` and `{hash}`.
|
|
338
|
+
|
|
339
|
+
Before pushing, steersync lists the other proposal branches of the same project still on
|
|
340
|
+
the remote and warns about them, so unmerged work is reviewed before more is added
|
|
341
|
+
(`branch.warn_existing`). `steersync status` prints the same list.
|
|
342
|
+
|
|
343
|
+
The merge request is opened in two ways:
|
|
344
|
+
|
|
345
|
+
1. **Push options.** The default `remote.push_options` ask GitLab to create a merge request
|
|
346
|
+
against the default branch, remove the source branch on merge and set a title. Servers
|
|
347
|
+
that do not advertise push options (GitHub, plain bare repositories) make git fail, so
|
|
348
|
+
steersync retries once without them and says so.
|
|
349
|
+
2. **GitLab API.** When the token variable is set (`GITLAB_TOKEN`, name configurable with
|
|
350
|
+
`gitlab.token_env`), `push` confirms or creates the merge request through the REST API and
|
|
351
|
+
prints its URL, and `steersync mr` (or the `raise_merge_request` MCP tool) does the same on
|
|
352
|
+
demand. The API base URL and project path are derived from `remote.url` and can be set
|
|
353
|
+
with `gitlab.api_url` and `gitlab.project`; `gitlab.target_branch` defaults to
|
|
354
|
+
`remote.default_branch`. The token is read from the environment only, never from a file,
|
|
355
|
+
and never logged.
|
|
356
|
+
|
|
357
|
+
## Validation
|
|
358
|
+
|
|
359
|
+
Each collection runs one lint profile: `steering`, `agent`, `hooks`, `skill`, `settings`,
|
|
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
|
|
366
|
+
the Kiro documentation, reported objectively and never blocking: a steering file with a
|
|
367
|
+
numeric prefix, an `auto` description that is not written as a trigger, a `globs` key where
|
|
368
|
+
Kiro reads `fileMatchPattern`, an agent with `tools: ["*"]` or a `file://.kiro/steering/**`
|
|
369
|
+
resource that loads everything at startup, inline agent hooks on CLI 3.0, a hook with a
|
|
370
|
+
15 minute timeout, a skill name that is not kebab case, an `mcp.json` with a home directory
|
|
371
|
+
path, more than 48 KiB of always on steering, missing `product.md`, `tech.md` and
|
|
372
|
+
`structure.md`. Every rule, its severity and the documentation page it comes from are listed
|
|
373
|
+
in [docs/validation.md](docs/validation.md); thresholds live under `lint.practice_limits`
|
|
374
|
+
and `lint.practices: false` turns the warnings off.
|
|
301
375
|
|
|
302
376
|
## Kiro integration
|
|
303
377
|
|
|
304
|
-
**Session hook (V3).** `steersync kiro-hook --write` creates
|
|
305
|
-
`SessionStart` trigger that runs
|
|
306
|
-
`steersync
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
378
|
+
**Session hook (V3).** `steersync init` (or `steersync kiro-hook --write`) creates
|
|
379
|
+
`.kiro/hooks/steersync.json` with a `SessionStart` trigger that runs
|
|
380
|
+
`steersync pull --quiet --best-effort`. For CLI 2.x agents paste the output of
|
|
381
|
+
`steersync kiro-hook --engine v2` into the agent's `hooks` block. Field reports say Kiro hooks
|
|
382
|
+
fire only in headless runs or with a custom agent active, so treat them as a convenience and
|
|
383
|
+
keep the git hook as the dependable trigger.
|
|
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
|
+
|
|
394
|
+
**MCP server.** `steersync init` registers the server in `.kiro/settings/mcp.json`
|
|
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
|
|
401
|
+
which request, so plain sentences work:
|
|
402
|
+
|
|
403
|
+
| Say | Tool |
|
|
404
|
+
|---|---|
|
|
405
|
+
| "pull / sync / refresh the kiro config", "update the steering and skills" | `pull_kiro_config` |
|
|
406
|
+
| "push / propose / share my kiro config", "sync my steering up" | `push_kiro_config` |
|
|
407
|
+
| "raise / open an MR for the kiro config", "merge request link" | `raise_merge_request` |
|
|
408
|
+
| "what changed", "status", "any open proposals for this repo" | `diff_kiro_config` |
|
|
409
|
+
| "validate / lint / check the kiro config, agents, hooks, skills" | `validate_kiro_config` |
|
|
410
|
+
| "what is synced and where" | `list_kiro_collections` |
|
|
411
|
+
| "am I on Kiro V3", "do my agents need upgrading" | `kiro_v3_status` |
|
|
412
|
+
|
|
413
|
+
Every tool accepts a `collections` list. Kiro does not pass the shell's `PATH`,
|
|
414
|
+
`SSH_AUTH_SOCK`, proxy variables or `GITLAB_TOKEN` to MCP servers, so the rendered entry
|
|
415
|
+
forwards them explicitly through `env`; use `steersync init --mcp-command /abs/path/uvx`
|
|
416
|
+
if `uvx` is not on Kiro's path.
|
|
315
417
|
|
|
316
418
|
**Custom agents.** On Kiro CLI V3 custom agents inherit steering, skills and `AGENTS.md` by
|
|
317
419
|
default, so list only the always on steering files in `resources` and reference skills with
|