nikos 0.1.1 → 0.2.0

package/skills/nikos-mode/playbooks/company.md

@@ -0,0 +1,16 @@
+# company
+
+Set a company up with nikOS from the top: a company plan repo that departments
+and teams join, the settings they inherit, and this period's objectives. Ask one
+question at a time, and do nothing outward-facing (creating a repo, sending
+anything) without a yes.
+
+1. Ask the company's name, the planning period, and its departments.
+2. Run `nikos company init --name "<name>" --period "<period>" --departments "<a, b>"` in an empty folder, or the company plan repo if one exists.
+3. Ask how approvals should work across the company: off, optional, or required before a release, and whether departments may change it. Save it with `nikos settings set approval.policy …`, and add it to `locked:` in `nikos.settings.yaml` if they say no.
+4. Run the tracker playbook to connect the company's tracker and map its statuses, here, so every level inherits it.
+5. Run the planning wizard at the company level for this period's objectives and key results. If they exist in a document already, read it through its MCP (Confluence, Google Docs, Notion) and draft from it.
+6. Ask whether to create the repo on GitHub or GitLab, and where. Only on a yes, create it with `gh` or `glab` (or the host's MCP), commit and push, and run `nikos company init --repo <path>` again to fill in the join line.
+7. Show the join line for each department and team, for the person to share however they like. Never send it yourself.
+   Later, "how's the rollout going?" runs `nikos planning rollout`: who has joined, who is behind, and delivery across their repos.
+8. Report every step with its evidence or its skip reason.

package/skills/nikos-mode/playbooks/index.md

@@ -6,9 +6,13 @@ first match. Packs add rows here as they ship new playbooks.
 | Playbook | File | Use when |
 | --- | --- | --- |
 | idea-to-blueprint | `idea-to-blueprint.md` | The person has a new product idea, or wants to start a project from scratch and there is no story map yet. |
+| company | `company.md` | The person wants to set nikOS up for a whole company or department: a company plan, settings every team inherits, and departments joining. |
+| start | `start.md` | The person wants to set nikOS up in this repo, or get started, and there's no `intent/` folder yet (or they ask to set it up again). |
+| map-existing | `map-existing.md` | The person wants a story map of a product that already exists: "map what this repo does", or nikOS on an existing codebase. |
 | video | `video.md` | The person asks for a video: an explainer, product tour, demo, launch or social clip, or to edit or re-render one. Needs the Video pack. |
 | validate | `validate.md` | The person wants to test or validate an idea with real people, or draft outreach, a post or a demo script for it. |
 | planning | `planning.md` | The person wants to plan a period, set OKRs or key results, frame or review a bet, check in on key results, or see a planning dashboard. Needs the Planning pack. |
+| tracker | `tracker.md` | The person wants to connect Jira, Linear, GitHub or GitLab issues, bring a tracker's backlog in, link stories to tickets, or bring the tracker and the story map back in step. |
 | build-a-story | `build-a-story.md` | The person asks to build, do or pick up the next story, or a story by its id. |
 | answer | `answer.md` | The person asks a question about the product, a story, a plan or a decision, and nothing in the repo needs to change. |
 | change | `change.md` | The person asks to add, fix, change or remove something in the repo: code, tests, docs or specs. |

package/skills/nikos-mode/playbooks/map-existing.md

@@ -0,0 +1,14 @@
+# map-existing
+
+Draft the story map from a product that already exists, so a team sees its own
+product mapped rather than an empty template. Nothing is written until the
+person agrees to the draft.
+
+1. Run `nikos start` if `intent/` doesn't exist yet.
+2. Survey the code: entry points, routes or screens, commands, and the tests that exist. Group what the product does into three to seven activities: the areas a person uses it for, in the order they'd use them.
+3. Under each activity, list the steps a person takes, and a story for each thing the product already lets them do, in the user's words (As a… I want… So that…), with the files that implement it.
+4. Show the draft as activities, steps and stories. Let the person rename, merge, drop or add. Write nothing until they agree.
+5. Write it: `nikos activity add` for each activity, `nikos step add` for each step, and `nikos story add` for each story, all in release 1. Remove the starter story `nikos init` made if nobody wants it.
+6. For each story, write scenarios that describe what the product does today, and step definitions that drive the real code. Run `nikos verify <story-id>`; when they pass, move the story to done with `nikos state set` (in_progress, then done). A scenario that fails is a finding: show it, and leave the story in_progress.
+7. Add a second release for what the person wants next, if they say.
+8. Report every step with its evidence or its skip reason, and how many stories are now proved done.

package/skills/nikos-mode/playbooks/start.md

@@ -0,0 +1,12 @@
+# start
+
+Set nikOS up in a repo and get to a first story that's proved done, in one
+conversation. Ask as little as possible: nikOS takes the name, key, stack and
+host from the repo.
+
+1. Run `nikos start`. It creates `intent/`, a scenario runner for the stack and CI for the host, each only if it's missing. Tell the person what it did in a sentence, not a list of files.
+2. Ask only what `nikos start` couldn't tell (its `?` lines), one question at a time, and finish the setup with the answer (`nikos verify setup`, `nikos ci setup --github` or `--gitlab`).
+3. If the repo already has code, run the map-existing playbook from here. If it's empty, ask what the product is for and who it's for, then run idea-to-blueprint from its step on the story map.
+4. Install the runner `nikos start` named, if it isn't installed, once the person agrees.
+5. Pick the first story with `nikos next` and build it with the build-a-story playbook, so the first session ends with one story's scenarios passing and the map showing it done.
+6. Report every step with its evidence or its skip reason.

package/skills/nikos-mode/playbooks/tracker.md

@@ -0,0 +1,14 @@
+# tracker
+
+Connect the story map to the team's tracker, bring a backlog in, or keep the
+two in step. nikOS never calls a tracker itself: you read and write tickets
+through the tracker's own MCP, and hand what you read to `nikos tracker`.
+
+1. Run `nikos settings`. If `tracker.system` is `none`, ask which tracker the team uses (Jira, Linear, GitHub Issues, GitLab Issues, Azure DevOps, Shortcut, or none). Read its guide in `trackers/<system>.md` next to the playbooks.
+2. Check the tracker's MCP is connected, as the guide describes. If it isn't, tell the person how to add it, and stop.
+3. With the MCP, list the statuses tickets can have in their project (or team). Propose what each means to nikOS (todo, in_progress, needs_rework, done, approved, cancelled), ask the person to confirm or change each one, and ask whether moving a ticket to an approved status should approve the story.
+4. Save the answers with `nikos settings set` (`tracker.system`, `tracker.site`, `tracker.project`, `tracker.statuses`, `tracker.approvals`). If this repo is a company or department plan, say that every repo joined to it inherits them, and ask whether to lock any.
+5. To bring a backlog in: fetch the tickets with the MCP, write them to a JSON file as `[{ "key", "title", "group" }]` (group: the epic, project or label), and run `nikos tracker import <file>`. Stories start as todo; offer to write the first ones' scenarios.
+6. To link stories that already exist: match each to its ticket with the person, and run `nikos tracker link <story-id> <ticket>`.
+7. To keep them in step: for each linked ticket, read its status (and, for an approved status, who moved it there from the ticket's history), and run `nikos tracker record <story-id> --status "<status>" --by "<who>"`. Then run `nikos tracker sync --json` and move each ticket it lists to the status it gives, with the MCP. Never move a story to done because a ticket says so: done comes from its scenarios.
+8. Report every step with its evidence or its skip reason.

package/skills/nikos-mode/trackers/github.md

@@ -0,0 +1,18 @@
+# GitHub Issues
+
+**MCP:** GitHub's MCP server, or the `gh` command when the agent has a shell.
+The person signs in through their app or `gh auth login`; you never handle a
+token.
+
+- **Project:** `tracker.project` is the repo (`owner/repo`), or a GitHub
+  Project if the team tracks work on a board. Tickets are issue numbers: link
+  them as `#57`.
+- **Statuses:** an issue is only open or closed. Teams on a GitHub Project
+  board use its Status field (Todo, In Progress, Done…): map those. Without a
+  board, map labels the team uses (`in-progress`, `approved`) as statuses.
+- **Who approved:** the issue's timeline says who closed it, or who changed
+  its Status field or labels.
+- **Backlog import:** list the open issues (or the board's items). Use the
+  milestone or a label as the group.
+- **Moving a ticket:** set the board's Status field, or the label, or close
+  the issue for done.

package/skills/nikos-mode/trackers/gitlab.md

@@ -0,0 +1,17 @@
+# GitLab Issues
+
+**MCP:** GitLab's MCP server, or the `glab` command when the agent has a
+shell. Self-managed GitLab works the same way, at the company's own host. The
+person signs in; you never handle a token.
+
+- **Project:** `tracker.site` is the host (`gitlab.com` or
+  `gitlab.acme.com`), `tracker.project` the project's full path
+  (`acme/product/payments`). Tickets are issue numbers: link them as `#57`.
+- **Statuses:** an issue is open or closed, and teams track the rest with
+  scoped labels (`workflow::in progress`, `workflow::approved`) or board
+  lists. Map the labels the team uses.
+- **Who approved:** the issue's history (system notes) says who added a label
+  or closed it.
+- **Backlog import:** list the open issues. Use the epic or milestone as the
+  group.
+- **Moving a ticket:** swap the scoped label, or close the issue for done.

package/skills/nikos-mode/trackers/jira.md

@@ -0,0 +1,19 @@
+# Jira
+
+**MCP:** Atlassian's MCP server (it covers Jira and Confluence). The person
+connects it in their app's connector or MCP settings and signs in with their
+Atlassian account; you never handle a token.
+
+- **Site and project:** `tracker.site` is the site's host (`acme.atlassian.net`),
+  `tracker.project` the project key (`PAY`). Ticket keys look like `PAY-123`.
+- **Statuses:** each project has its own workflow, so list the statuses for
+  this project, not the site. Common ones: To Do, In Progress, In Review,
+  Done, and often an "Accepted" or "Approved" a product owner moves tickets
+  to.
+- **Who approved:** an issue's changelog says who moved it to each status
+  and when. Use that for `--by`, never the assignee.
+- **Backlog import:** search the project's open issues with JQL
+  (`project = PAY AND statusCategory != Done`). Use the epic as the group.
+- **Moving a ticket:** Jira moves issues by transition, not by setting a
+  status. List the issue's transitions and pick the one that leads to the
+  status `nikos tracker sync` gives.

package/skills/nikos-mode/trackers/linear.md

@@ -0,0 +1,17 @@
+# Linear
+
+**MCP:** Linear's own MCP server. The person connects it in their app and
+signs in to Linear; you never handle a key.
+
+- **Team:** Linear groups issues by team, not project. `tracker.project` is
+  the team key (`ENG`); ticket ids look like `ENG-42`. `tracker.site` is the
+  workspace's url name.
+- **Statuses:** each team has its own workflow states, grouped as backlog,
+  unstarted, started, completed and canceled. Map the team's states, not the
+  groups.
+- **Who approved:** an issue's history says who changed its state. Use that
+  for `--by`.
+- **Backlog import:** list the team's issues that aren't completed or
+  canceled. Use the project (or the parent issue) as the group.
+- **Moving a ticket:** set the issue's state to the one `nikos tracker sync`
+  gives.

package/skills/verify/SKILL.md

@@ -47,3 +47,12 @@ Pending or unimplemented steps count as not passing.
 Report the command and the runner's summary line, such as
 `2 scenarios (2 passed)`. If anything failed or is pending, show the output
 and don't call the story done.
+
+## 5. Run it on every PR or merge request (once per repo)
+
+When the person wants the checks to run in CI, run `nikos ci setup`. It reads
+the origin remote to pick GitHub Actions (`.github/workflows/nikos.yml`) or
+GitLab CI (`.gitlab/ci/nikos.yml`, included from `.gitlab-ci.yml`). Pass
+`--github` or `--gitlab` when there's no remote yet. If the repo already has a
+`.gitlab-ci.yml`, it prints the `include:` lines to add: add them, and show the
+person the change.