@ggdna/dna-gg 0.13.0 → 0.14.0

package/README.md

@@ -9,7 +9,15 @@ publish.
   `dna/doc/guides/develop-without-ai-guide.md` — the ticket driven
   workflow, with and without an AI
 - `dna/doc/guides/for-ai/ai-dev-guide.md` — the same workflow as
-  instructions for an agent
+  instructions for an agent. Its section "Keep every repo in its scope"
+  makes the agent propose on its own to split a repo, add a new or an
+  existing one, or move code, whenever code leaves the scope of its repo
+  — and its section "Keep the index.jsonc up to date" makes it update the
+  `index.jsonc` with every code change that alters what the repo does or
+  uses, and create it in every repo of a ticket that has none yet. Its
+  section "Describe every repo in its own terms" keeps the parent repos of
+  a ticket out of what the agent writes into their dependencies: commit
+  and merge messages, changelog, blog posts, code comments, `index.jsonc`
 - `dna/doc/guides/install-guide/install-gg-guide.md`,
   `dna/doc/guides/install-guide/install-gg-workspace-guide.md` — install
   `gg` and set up a workspace
@@ -26,10 +34,12 @@ publish.
 All skills of this layer are prefixed with `gg-`:
 
 - `/gg` — lists the skills below and says which one comes next
-- `/gg-ticket` — creates a ticket and adds the repos it needs
+- `/gg-ticket` — creates a ticket, adds the repos it needs and keeps
+  every repo in its scope
 - `/gg-commit` — proposes a message and commits through `gg do commit`
 - `/gg-push` — pushes the ticket branches
-- `/gg-review` — writes the blog posts and opens the pull requests
+- `/gg-review` — checks the scope of every repo, writes the blog posts
+  and opens the pull requests
 - `/gg-publish` — releases the ticket
 - `/gg-cleanup` — removes what the ticket left behind
 
@@ -91,9 +101,11 @@ appends the `Workspace` section.
 - `dnaJiraPrefix` — the prefix of a ticket id
 - `dnaGitQuickCheckPipelineName` — the name the branch rules require
 - `dnaPubDevPublisher` — the pub.dev publisher packages are transferred to
-- `dnaPmRepo` — the project management repo the prompts go to: a repo
-  name beside the repo's own origin, or a full git URL. Empty by default,
-  then no prompt is kept
+- `dnaPmRepo` — the project management repo the prompts go to: its name
+  with `.git` appended, e.g. `my_pm.git`, which finds it beside the repo's
+  own origin, or a full git URL. helix re-cases a bare name like `my_pm`
+  to the case of the reference, `.git` keeps it as written. Empty by
+  default, then no prompt is kept
 
 `dnaCopyrightHolder`, `dnaCompany` and `dnaJiraPrefix` name the
 organization, so they are never inherited: every layer or project listing

package/dna/_generated.json

@@ -39,7 +39,7 @@
       "ecosystem": null,
       "resolvedVersion": null,
       "via": null,
-      "hash": "0x5cf663c108f9dc04"
+      "hash": "0xb282e7ad6fa403dc"
     }
   ],
   "claude": {
@@ -55,7 +55,7 @@
     },
     {
       "path": ".claude/hooks/pm-prompts.mjs",
-      "hash": "0xd579ad4abeb87732"
+      "hash": "0x988aed96a8073727"
     },
     {
       "path": ".claude/settings.json",
@@ -67,7 +67,7 @@
     },
     {
       "path": ".claude/skills/gg-commit/SKILL.md",
-      "hash": "0xdb7a268397facfc4"
+      "hash": "0x7fbe4b075588fc4d"
     },
     {
       "path": ".claude/skills/gg-publish/SKILL.md",
@@ -79,11 +79,11 @@
     },
     {
       "path": ".claude/skills/gg-review/SKILL.md",
-      "hash": "0x09df48b6f6bf1de6"
+      "hash": "0x9f7bbbe511238684"
     },
     {
       "path": ".claude/skills/gg-ticket/SKILL.md",
-      "hash": "0xa238364995ac50f8"
+      "hash": "0xc238102fbb3eda52"
     },
     {
       "path": ".claude/skills/gg/SKILL.md",
@@ -111,7 +111,7 @@
     },
     {
       "path": "doc/guides/for-ai/ai-dev-guide.md",
-      "hash": "0xb4ae698a82bc9e2c"
+      "hash": "0xba608ae9efe904ab"
     },
     {
       "path": "doc/guides/index-guide.md",

package/dna/doc/guides/for-ai/ai-dev-guide.md

@@ -73,11 +73,12 @@ confirmation; add the repos as shown below.
 Automatically: look at the `index.jsonc` of each repo in .ocean and decide
 which repos need to be added to the ticket.
 Make a plan for how you roughly want to implement the ticket.
-If certain parts of the implementation belong to a domain that does not yet
-exist in the .ocean folder, consider creating a new repository.
-Ask the user about this. Also explain to the user what you roughly want to
-change in which repo to implement the ticket and let them confirm that the
-corresponding repos are added to the ticket.
+Check the plan against the scope of each repo (see
+[Keep every repo in its scope](#keep-every-repo-in-its-scope)) and propose
+a split, a new repo or a move wherever a part does not fit.
+Also explain to the user what you roughly want to change in which repo to
+implement the ticket and let them confirm that the corresponding repos are
+added to the ticket.
 
 If the ticket is only planned (see below), the project management repo may
 be the only repo of the ticket.
@@ -88,6 +89,47 @@ After the user's confirmation, add the repos to the ticket:
 gg do add repo1 repo2
 ```
 
+## Keep every repo in its scope
+
+Every repo covers one fixed scope: the `summary` and `domain` of its
+`index.jsonc`. If a repo has none, take the scope from its README.md and
+create the `index.jsonc` with the first change of the ticket in that repo
+(see [Keep the index.jsonc up to date](#keep-the-indexjsonc-up-to-date)).
+Code outside that scope blurs the repo. Check the scope whenever you decide
+where code goes — while choosing the repos, while implementing and before
+the review — and propose a change on your own, without being asked, as soon
+as code does not fit the repo it is in or is about to land in:
+
+- **Split a repo** — the repo has grown a second scope: propose splitting
+  it into two repos, each with a scope of its own
+- **Add a new repo** — the code belongs to a domain no repo in .ocean
+  covers: propose creating one with `gg do create repo`, which adds it to
+  the ticket
+- **Add an existing repo** — the code belongs to a repo in .ocean that is
+  not part of the ticket yet: propose adding it with `gg do add`
+- **Move code** — existing code, or code you just wrote, belongs to another
+  repo: propose moving it there
+
+For each proposal, name the code concerned, the repo it is in, the repo it
+should go to, and why it fits the scope of that repo better. Then let the
+user decide:
+
+- **Now** — change it within this ticket: add or create the repo, move the
+  code, and adjust the dependencies and imports of both sides
+- **Later** — keep it as a follow-up ticket: in the project management repo
+  if the ticket has one, otherwise in the ticket. Continue with the code
+  where it is.
+
+Whenever the scope of a repo changes, update the `index.jsonc` of each repo
+concerned (see
+[Keep the index.jsonc up to date](#keep-the-indexjsonc-up-to-date)): a new
+or split-off repo gets its own `summary` and `domain`, the repo that gives
+code away is narrowed accordingly, and `interfaces.uses` and
+`interfaces.usedBy` follow the new dependencies.
+
+Never split a repo, add or create one, or move code without the user's
+confirmation.
+
 ## Open the workspace in Vscode
 
 ```bash
@@ -117,10 +159,67 @@ Ask the user whether the ticket is implemented now, or whether it is only
 planned. Some tickets are only planned; the implementation follows in a later
 ticket.
 
-- Implement: implement your features based on the guides
+- Implement: implement your features based on the guides. Write the code
+  comments and documentation of a dependency in its own terms, without its
+  parents (see
+  [Describe every repo in its own terms](#describe-every-repo-in-its-own-terms)).
+  Keep every repo in its scope while you code: stop and propose a split,
+  a new repo or a move as soon as code does not fit (see
+  [Keep every repo in its scope](#keep-every-repo-in-its-scope))
 - Plan only: skip this step. The following steps then apply to the project
   management repo only.
 
+## Keep the index.jsonc up to date
+
+The `index.jsonc` of a repo describes what the repo is: its `summary`, its
+`domain` and its `interfaces`. Other agents choose the repos of a ticket by
+it, so it must match the code at all times, not only at the review.
+
+Whenever you change code in a repo, check whether its `index.jsonc` still
+matches and update it in the same step:
+
+- `summary` and `domain` — when the repo can do something new, no longer
+  does something, or its scope changed
+- `interfaces.uses` — when the repo starts or stops using another repo, or
+  uses a different API of it
+- `interfaces.usedBy` — when another repo starts or stops using this one;
+  update the `uses` of that repo too, so both sides agree
+
+A repo without `index.jsonc` gets one with the first change of the ticket,
+whatever the change: copy `doc/templates/index-template.jsonc` to
+`index.jsonc` and fill it from the README.md and the code. Never leave a
+repo of the ticket without one.
+
+Follow `doc/guides/index-guide.md`: keywords instead of sentences, the
+fields of the template only. Once the file exists, a change that leaves all
+three fields true — a bug fix, a refactoring inside the repo — needs no
+update.
+
+## Describe every repo in its own terms
+
+A ticket often changes a repo together with one of its dependencies: the
+parent repo uses the dependency. The dependency does not know its parents,
+so what you write into it describes its own change only — never why a
+parent needs it. This holds for everything you write into the dependency:
+
+- commit messages, `nextCommitMessage` and `mergeMessage` — and with them
+  the `CHANGELOG.md` entry and the pull request title
+- blog posts
+- code comments and documentation
+- its `index.jsonc`, except `interfaces.usedBy`, which names the parents
+  on purpose
+
+Never name a parent repo there, nor the goal of the ticket or the use case
+of the parent. The parent, in turn, may name the dependency and what it
+uses of it.
+
+- Wrong in `gg_git`: `Add remote creation for gg do create repo`
+- Right in `gg_git`: `Add a function that creates a remote repository`
+- Right in `gg`: `Create the remote repository with gg_git`
+
+Which repo depends on which is in `interfaces.uses` of the `index.jsonc`,
+and in `pubspec.yaml` or `package.json`.
+
 ## Keep the publish config up to date
 
 Each repo of the ticket has a file `.gg/publish_config.json`. gg offers its
@@ -146,7 +245,8 @@ to change and keep the rest — `commits` is written by gg, never by hand.
 }
 ```
 
-- `firstLine`: imperative, at most 60 characters
+- `firstLine`: imperative, at most 60 characters, in the terms of the
+  repo itself (see [Describe every repo in its own terms](#describe-every-repo-in-its-own-terms))
 - `details`: optional, one entry per line
 - `mergeMessage`: the pull request title and the merge commit message of
   the repo
@@ -163,6 +263,19 @@ ticket folder reads `nextCommitMessage`; `gg one do commit` does not.
 gg do commit
 ```
 
+Every repo gets its own message. When repos of the ticket depend on each
+other, never commit them with one `-m` for all. Commit each repo on its own
+with its `nextCommitMessage` (see
+[Describe every repo in its own terms](#describe-every-repo-in-its-own-terms)):
+
+```bash
+cd repo1
+gg one do commit -m"<nextCommitMessage of repo1>"
+```
+
+`gg do commit` without `-m` offers the same messages, but in an editor the
+user has to confirm — leave that way to the user.
+
 `gg do commit` and `gg can commit` act on all repos of the ticket. When you
 are inside a single repo instead of the ticket folder, use the standalone
 form on that repo:
@@ -180,12 +293,19 @@ gg do push
 
 ## Review
 
-Document the change in every repo first, so the documentation lands in
-the pull requests and is reviewed with the code:
+Check the diff of every repo of the ticket against its scope first (see
+[Keep every repo in its scope](#keep-every-repo-in-its-scope)) and propose
+a split, a new repo or a move for everything that does not fit.
+
+Then document the change in every repo, so the documentation lands in the
+pull requests and is reviewed with the code:
 
 - Run `/blog` in every repo of the ticket that has
-  `doc/guides/blog-guide.md`, the project management repo included
-- Update the index.jsonc and README.md
+  `doc/guides/blog-guide.md`, the project management repo included. A
+  dependency's post describes its own change, without its parents (see
+  [Describe every repo in its own terms](#describe-every-repo-in-its-own-terms))
+- Update the README.md, and check once more that every repo has an
+  `index.jsonc` and that it matches the code of the ticket
 - Commit and push again
 
 Let the user confirm that the review phase is started.

package/dna/dot-claude/hooks/pm-prompts.mjs

@@ -157,14 +157,17 @@ function originOf(dir, depth = 0) {
 /**
  * The URL of the project management repo [pmRepo] beside the repo cloned
  * from [origin]: same host, same organization. A full URL is taken as is.
+ * The name may end in `.git`: the DNA writes it that way, because helix
+ * would re-case a bare name like `my_pm` into `myPm`.
  */
 export function pmRepoUrl(pmRepo, origin) {
   if (!pmRepo) return '';
   if (/^[a-z][a-z0-9+.-]*:\/\/|^[^/\\\s]+@[^/\\\s]+:/i.test(pmRepo)) {
     return pmRepo;
   }
+  const name = pmRepo.replace(/\.git$/, '');
   const match = (origin ?? '').match(/^(.*[/:\\])[^/:\\]+?(\.git)?[/\\]?$/);
-  return match ? `${match[1]}${pmRepo}${match[2] ?? ''}` : '';
+  return match ? `${match[1]}${name}${match[2] ?? ''}` : '';
 }
 
 /**

package/dna/dot-claude/skills/gg-commit/SKILL.md

@@ -20,19 +20,40 @@ whenever you are inside a repo.
 
 ## 2. Propose a message
 
-Look at `git status` and `git diff` in the repos of the ticket. Propose one
-imperative one-liner that says what the step does, not which files changed.
-Start from `nextCommitMessage` in `.gg/publish_config.json` of each repo and
-update it there if it no longer matches the diff (see the development
-guide). Let the user confirm it.
+Look at `git status` and `git diff` in the repos of the ticket. Propose
+for each repo an imperative one-liner that says what the step does in that
+repo, not which files changed. Start from `nextCommitMessage` in
+`.gg/publish_config.json` of each repo and update it there if it no longer
+matches the diff (see the development guide). Let the user confirm them.
+
+A dependency describes its change in its own terms. When a repo of the
+ticket uses another one, the message of the dependency never names the
+parent repo, the goal of the ticket or the use case of the parent — the
+parent may name the dependency. The same holds for the `mergeMessage`.
+
+- Wrong in `gg_git`: `Add remote creation for gg do create repo`
+- Right in `gg_git`: `Add a function that creates a remote repository`
+- Right in `gg`: `Create the remote repository with gg_git`
+
+Section "Describe every repo in its own terms" of
+`doc/guides/for-ai/ai-dev-guide.md` has the details.
+
+Check in the same pass whether the diff changes what the `index.jsonc` of
+the repo says — its `summary`, `domain` or `interfaces` — and update it
+before committing. If the repo has no `index.jsonc`, create it now from
+`doc/templates/index-template.jsonc`, whatever the diff. Section "Keep the
+index.jsonc up to date" of `doc/guides/for-ai/ai-dev-guide.md` has the
+details.
 
 If the user runs `gg do commit` in the ticket folder without `-m`, the
 editor already shows each repo's `nextCommitMessage` — `-m` overrides it
-with one message for all repos.
+with one message for all repos. Use `-m` in the ticket folder only when no
+repo of the ticket depends on another; otherwise commit each repo on its
+own with `gg one do commit -m` and its `nextCommitMessage`.
 
 ## 3. Commit
 
-From the ticket folder:
+From the ticket folder, when no repo of the ticket depends on another:
 
 ```bash
 gg do commit -m"<message>"
@@ -56,4 +77,5 @@ its source under `dna/` instead.
 ## Important
 
 - Never commit without the confirmed message.
+- Never let a parent repo leak into the message of its dependency.
 - Never push here — that is `/gg-push`.

package/dna/dot-claude/skills/gg-review/SKILL.md

@@ -9,19 +9,36 @@ Each repo documents its change first, so the documentation lands in the
 pull requests and is reviewed with the code. Every commit after
 `gg do review` voids the review.
 
-## 1. Document the change in every repo
+## 1. Check the scope of every repo
+
+Every repo covers one fixed scope: the `summary` and `domain` of its
+`index.jsonc`, or its README.md if it has none. Read the diff of every repo
+of the ticket against that scope. For code that does not fit, propose on
+your own a split of the repo, a new repo, an existing repo to add, or a
+move of the code into the repo whose scope it fits — with the reason. Let
+the user decide whether it changes now, within this ticket, or later, as a
+follow-up ticket. Section "Keep every repo in its scope" of
+`doc/guides/for-ai/ai-dev-guide.md` has the details.
+
+## 2. Document the change in every repo
 
 Look for `doc/guides/blog-guide.md` in every repo of the ticket, the
 project management repo included. It comes from the `dna_blog` layer.
 
 - Run `/blog` in each repo that has it; skip the others
+- A dependency's post describes its own change only: it never names the
+  repos of the ticket that use it, nor their goal — section "Describe
+  every repo in its own terms" of `doc/guides/for-ai/ai-dev-guide.md`
 - `/blog` stops by itself when the post already exists
 
-Update `index.jsonc` and `README.md` of each repo the ticket changed.
+Update `README.md` of each repo the ticket changed. Check once more that
+each of them has an `index.jsonc` — create it from
+`doc/templates/index-template.jsonc` if not — and that it matches the code
+of the ticket.
 
 Let the user review the changes, then run `/gg-commit` and `/gg-push`.
 
-## 2. Open the pull requests
+## 3. Open the pull requests
 
 Let the user confirm that the review phase is started. From the ticket
 folder:
@@ -33,7 +50,7 @@ gg do review
 gg creates a pull request for each repo and prints the URLs to the
 terminal.
 
-## 3. Review the changes
+## 4. Review the changes
 
 Load the `/review-light` skill and execute it.
 

package/dna/dot-claude/skills/gg-ticket/SKILL.md

@@ -55,10 +55,12 @@ Call it the "project management repo" whenever you write to the user, never
 Ask the user how the code repos are chosen, as a single question with two
 options:
 
-- **automatically** — Claude finds the repos. Read the `index.md` of the
-  candidate repos in `.ocean`. Tell the user which repos the ticket needs
-  and what you roughly want to change in each one. If a part belongs to a
-  domain that has no repo yet, say so and ask whether to create one.
+- **automatically** — Claude finds the repos. Read the `index.jsonc` of
+  the candidate repos in `.ocean`. Tell the user which repos the ticket
+  needs and what you roughly want to change in each one. Check each part
+  against the scope of its repo and propose a split, a new repo or a move
+  wherever a part does not fit (see
+  [Keep every repo in its scope](#keep-every-repo-in-its-scope)).
 - **manually** — the user names the repos. Ask in a second single input
   field which repos the ticket needs, e.g. `repo1 repo2`. Check each name
   against the repos in `.ocean` and ask again for names that do not exist
@@ -93,8 +95,38 @@ confirm it there. Then ask whether the ticket is implemented now or only
 planned — in the latter case the ticket ends with the project management
 repo alone.
 
+While implementing, write the code comments and documentation of a
+dependency in its own terms: never name the repos of the ticket that use
+it, nor their goal (section "Describe every repo in its own terms" of
+`doc/guides/for-ai/ai-dev-guide.md`). Keep every repo in its scope: stop
+and propose a split, a new repo or a move as soon as code does not fit (see
+below). With every code change, check whether the `index.jsonc` of the repo
+still matches and update it in the same step; a repo without one gets it
+with its first change — section "Keep the index.jsonc up to date" of
+`doc/guides/for-ai/ai-dev-guide.md` says when and how.
+
+## Keep every repo in its scope
+
+Every repo covers one fixed scope: the `summary` and `domain` of its
+`index.jsonc`, or its README.md as long as it has none. From choosing the
+repos until the review, propose a change on your own as soon as code does
+not fit the repo it is in or is about to land in:
+
+- **Split a repo** that has grown a second scope into two repos
+- **Add a new repo** with `gg do create repo` for a domain no repo covers
+- **Add an existing repo** with `gg do add` when the code belongs there
+- **Move code**, existing or just written, into the repo whose scope it fits
+
+Name the code, the repo it is in, the repo it should go to and why. Let the
+user decide whether it changes now, within this ticket, or later, as a
+follow-up ticket. After a change of scope, update the `index.jsonc` of each
+repo concerned. Section "Keep every repo in its scope" of
+`doc/guides/for-ai/ai-dev-guide.md` has the details.
+
 ## Important
 
 - Never add repos without confirmation — a manually entered list counts as
   one. Rather too few than too many — more can be added later.
 - Do not start the implementation unasked.
+- Never split a repo, add or create one, or move code without the user's
+  confirmation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggdna/dna-gg",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "DNA layer: gg CLI workflow guides, repo setup scripts and CI check",
   "keywords": [
     "dna",