@xn-intenton-z2a/agentic-lib 7.1.26 → 7.1.27

package/README.md

@@ -23,16 +23,20 @@ Or start from the [repository0 template](https://github.com/xn-intenton-z2a/repo
 MISSION.md           Your project goals in plain English
     |
     v
-[agentic-step]       GitHub Action wrapping the Copilot SDK
+[supervisor]         LLM gathers repo state, picks actions
     |
-    v
+    +-----+-----+-----+-----+
+    v     v     v     v     v
+ transform  maintain  review  fix  discussions
+    |         |        |      |       |
+    v         v        v      v       v
 Issue -> Code -> Test -> PR -> Merge -> Next Issue
     ^                                       |
     +---------------------------------------+
               Autonomous cycle
 ```
 
-The pipeline runs as GitHub Actions workflows on a schedule. Each step uses the `agentic-step` action to call the Copilot SDK with context from your repository (mission, contributing guidelines, existing code, test results) and produce targeted changes.
+An LLM supervisor runs on a configurable schedule, gathers full repository context (open issues, PRs, workflow runs, features, activity), and strategically dispatches other workflows. Each workflow uses the `agentic-step` action to call the Copilot SDK with context from your repository and produce targeted changes. Users can interact with the system through a GitHub Discussions bot, which relays requests to the supervisor.
 
 ## Initialisation
 
@@ -69,10 +73,10 @@ your-repo/
 │   │
 │   └── agentic-lib/                          # [INIT] Internal infrastructure (always overwritten)
 │       ├── actions/
-│       │   ├── agentic-step/                 #   The Copilot SDK action (8 task handlers)
+│       │   ├── agentic-step/                 #   The Copilot SDK action (9 task handlers)
 │       │   ├── commit-if-changed/            #   Composite: conditional git commit
 │       │   └── setup-npmrc/                  #   Composite: npm registry auth
-│       ├── agents/                           #   7 prompt files + config YAML
+│       ├── agents/                           #   8 prompt files + config YAML
 │       ├── seeds/                            #   Seed files for reset
 │       └── scripts/                          #   Utility scripts
 │
@@ -104,13 +108,48 @@ The `init.yml` workflow is distributed from seeds (like `test.yml`) and runs `np
 
 ### GitHub Repository Settings
 
-After `init`, configure these in your GitHub repository:
+After `init`, configure your GitHub repository with the following tokens, permissions, and settings.
+
+#### Required Secrets
+
+| Secret | Type | Permissions | Purpose |
+|--------|------|-------------|---------|
+| `COPILOT_GITHUB_TOKEN` | Fine-grained PAT | **Copilot** (read) | Authenticates with the GitHub Copilot SDK for all agentic tasks |
+| `WORKFLOW_TOKEN` | Classic PAT | **workflow** scope | Required by `init.yml` to push workflow file changes (GITHUB_TOKEN cannot modify `.github/workflows/`) |
+
+**Creating `COPILOT_GITHUB_TOKEN`:**
+1. Go to [github.com/settings/tokens](https://github.com/settings/tokens) → Fine-grained tokens → Generate new token
+2. Set repository access to your target repo (or all repos)
+3. Under "Account permissions", enable **GitHub Copilot** → Read
+4. Copy the token and add it as a repository secret: Settings → Secrets and variables → Actions → New repository secret
+
+**Creating `WORKFLOW_TOKEN`:**
+1. Go to [github.com/settings/tokens](https://github.com/settings/tokens) → Tokens (classic) → Generate new token
+2. Select the **workflow** scope (this includes repo access)
+3. Set expiration (max 90 days for enterprise orgs)
+4. Copy the token and add it as a repository secret
+
+#### Repository Settings
+
+| Setting | Where | Value | Purpose |
+|---------|-------|-------|---------|
+| GitHub Actions | Settings → Actions → General | Allow all actions | Workflows must be able to run |
+| Workflow permissions | Settings → Actions → General | Read and write | Workflows need to create branches, PRs, and push commits |
+| Allow GitHub Actions to create PRs | Settings → Actions → General | Checked | Required for automerge and init workflows |
+| GitHub Discussions | Settings → General → Features | Enabled | Required for the discussions bot |
+| Branch protection (optional) | Settings → Branches | Require PR reviews | Recommended: prevents direct pushes, ensures review |
+
+#### Permissions Summary
+
+The workflows use `permissions: write-all` in the workflow files. The key permissions used are:
 
-| Setting | Where | Purpose |
-|---------|-------|---------|
-| `COPILOT_GITHUB_TOKEN` | Settings > Secrets | Fine-grained PAT with "Copilot Requests" permission |
-| GitHub Actions | Settings > Actions | Must be enabled (default) |
-| Branch protection | Settings > Branches | Optional: require PR reviews before merge |
+| Permission | Used by | Purpose |
+|------------|---------|---------|
+| `contents: write` | All agent workflows | Create branches, push commits |
+| `pull-requests: write` | Transform, fix-code | Create and update PRs |
+| `issues: write` | Review, enhance, supervisor | Create, label, close issues |
+| `actions: write` | Supervisor | Dispatch other workflows |
+| `discussions: write` | Discussions bot | Post replies to discussions |
 
 ## Configuration
 
@@ -118,16 +157,20 @@ Configuration lives in `agentic-lib.toml` at your project root:
 
 ```toml
 [schedule]
-tier = "schedule-1"       # schedule-1 through schedule-4
+tier = "schedule-1"          # schedule-1 through schedule-4
+supervisor = "daily"         # off | weekly | daily | hourly | continuous
 
 [paths]
 mission = "MISSION.md"
 source = "src/lib/"
 tests = "tests/unit/"
 features = "features/"
+library = "library/"
 docs = "docs/"
 readme = "README.md"
 dependencies = "package.json"
+contributing = "CONTRIBUTING.md"
+library-sources = "SOURCES.md"
 
 [execution]
 build = "npm run build"
@@ -139,6 +182,8 @@ feature-issues = 2
 maintenance-issues = 1
 attempts-per-branch = 3
 attempts-per-issue = 2
+features-limit = 4
+library-limit = 32
 
 [bot]
 log-file = "intentïon.md"
@@ -152,6 +197,7 @@ The core of the system is a single GitHub Action that handles all autonomous tas
 
 | Task | Purpose |
 |------|---------|
+| `supervise` | Gather repo context, choose and dispatch actions strategically |
 | `transform` | Transform the codebase toward the mission |
 | `resolve-issue` | Read an issue and generate code to resolve it |
 | `fix-code` | Fix failing tests or lint errors |
@@ -161,7 +207,7 @@ The core of the system is a single GitHub Action that handles all autonomous tas
 | `review-issue` | Review and close resolved issues |
 | `discussions` | Respond to GitHub Discussions |
 
-Each task calls the GitHub Copilot SDK with context assembled from your repository (mission, code, tests, features) and writes changes back to the working tree.
+Each task calls the GitHub Copilot SDK with context assembled from your repository (mission, code, tests, features) and writes changes back to the working tree. The supervisor can dispatch any of the other tasks via workflow dispatch.
 
 ## CLI Task Commands
 
@@ -277,16 +323,16 @@ This repository is the source for the `@xn-intenton-z2a/agentic-lib` npm package
 
 ```
 src/
-├── workflows/     7 GitHub Actions workflow templates
+├── workflows/     8 GitHub Actions workflow templates
 ├── actions/       3 composite/SDK actions (agentic-step, commit-if-changed, setup-npmrc)
-├── agents/        7 agent prompt files + 1 config
+├── agents/        8 agent prompt files + 1 config
 ├── seeds/         7 seed files (test.yml + 6 project seed files for --purge reset)
 └── scripts/       7 utility scripts distributed to consumers
 ```
 
 ### Testing
 
-236 unit tests across 21 test files, plus system tests:
+269 unit tests across 22 test files, plus system tests:
 
 ```bash
 npm test                  # Run all tests (vitest)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xn-intenton-z2a/agentic-lib",
-  "version": "7.1.26",
+  "version": "7.1.27",
   "description": "Agentic-lib Agentic Coding Systems SDK powering automated GitHub workflows.",
   "type": "module",
   "scripts": {

package/src/seeds/init.yml

@@ -27,6 +27,11 @@ on:
         type: boolean
         required: false
         default: false
+      mission:
+        description: "Mission text for MISSION.md (leave empty to use seed default)"
+        type: string
+        required: false
+        default: ""
 
 permissions: write-all
 
@@ -42,9 +47,12 @@ jobs:
           echo "mode=${MODE:-update}" >> $GITHUB_OUTPUT
           DRY_RUN='${{ inputs.dry-run }}'
           echo "dry-run=${DRY_RUN:-false}" >> $GITHUB_OUTPUT
+          MISSION='${{ inputs.mission }}'
+          echo "mission=${MISSION}" >> $GITHUB_OUTPUT
     outputs:
       mode: ${{ steps.normalise.outputs.mode }}
       dry-run: ${{ steps.normalise.outputs.dry-run }}
+      mission: ${{ steps.normalise.outputs.mission }}
 
   init:
     needs: params
@@ -52,6 +60,7 @@ jobs:
     env:
       INIT_MODE: ${{ needs.params.outputs.mode }}
       INIT_DRY_RUN: ${{ needs.params.outputs.dry-run }}
+      INIT_MISSION: ${{ needs.params.outputs.mission }}
     steps:
       - uses: actions/checkout@v4
         with:
@@ -78,6 +87,12 @@ jobs:
           if [ "$INIT_DRY_RUN" = "true" ]; then FLAGS="$FLAGS --dry-run"; fi
           npx @xn-intenton-z2a/agentic-lib $FLAGS
 
+      - name: Write mission (if provided)
+        if: env.INIT_MISSION != ''
+        run: |
+          printf '# Mission\n\n%s\n' "$INIT_MISSION" > MISSION.md
+          echo "Wrote custom mission to MISSION.md"
+
       - run: npm install
 
       - name: Install agentic-step deps

package/src/seeds/zero-README.md

@@ -1,13 +1,79 @@
 # repo
 
-Describe your project here.
+This repository is powered by [intentïon agentic-lib](https://github.com/xn-intenton-z2a/agentic-lib) — autonomous code transformation driven by GitHub Copilot. Write a mission, and the system generates issues, writes code, runs tests, and opens pull requests on a schedule.
 
 ## Getting Started
 
-1. Write your mission in `MISSION.md`
-2. Enable GitHub Actions
-3. The workflows will evolve `src/lib/main.js` toward your mission
+1. **Write your mission** in [`MISSION.md`](MISSION.md) — describe what you want to build in plain English
+2. **Configure GitHub** — see [Setup](#setup) below
+3. **Push to main** — the autonomous workflows take over from here
+
+The system will create issues from your mission, generate code to resolve them, run tests, and open PRs. A supervisor agent orchestrates the pipeline, and you can interact through GitHub Discussions.
+
+## Setup
+
+### Required Secrets
+
+Add these in your repository: **Settings → Secrets and variables → Actions → New repository secret**
+
+| Secret | How to create | Purpose |
+|--------|---------------|---------|
+| `COPILOT_GITHUB_TOKEN` | [Fine-grained PAT](https://github.com/settings/tokens?type=beta) with **GitHub Copilot** → Read permission | Authenticates with the Copilot SDK for all agentic tasks |
+| `WORKFLOW_TOKEN` | [Classic PAT](https://github.com/settings/tokens) with **workflow** scope | Allows `init.yml` to update workflow files (GITHUB_TOKEN cannot modify `.github/workflows/`) |
+
+### Repository Settings
+
+| Setting | Where | Value |
+|---------|-------|-------|
+| GitHub Actions | Settings → Actions → General | Allow all actions |
+| Workflow permissions | Settings → Actions → General | Read and write permissions |
+| Allow GitHub Actions to create PRs | Settings → Actions → General | Checked |
+| GitHub Discussions | Settings → General → Features | Enabled (for the discussions bot) |
+
+### Optional: Branch Protection
+
+For production repositories, consider adding branch protection on `main`:
+- Require pull request reviews before merging
+- Require status checks to pass (select the `test` workflow)
+
+## How It Works
+
+```
+MISSION.md → [supervisor] → dispatch workflows → Issue → Code → Test → PR → Merge
+                                                    ↑                          |
+                                                    +——————————————————————————+
+```
+
+The pipeline runs as GitHub Actions workflows. An LLM supervisor gathers repository context (issues, PRs, workflow runs, features) and strategically dispatches other workflows. Each workflow uses the Copilot SDK to make targeted changes.
+
+## Configuration
+
+Edit `agentic-lib.toml` to tune the system:
+
+```toml
+[schedule]
+supervisor = "daily"    # off | weekly | daily | hourly | continuous
+
+[paths]
+mission = "MISSION.md"
+source = "src/lib/"
+tests = "tests/unit/"
+
+[limits]
+feature-issues = 2      # max concurrent feature issues
+attempts-per-issue = 2   # max retries per issue
+```
+
+## Updating
+
+The `init.yml` workflow runs daily and updates the agentic infrastructure automatically. To update manually:
+
+```bash
+npx @xn-intenton-z2a/agentic-lib@latest init
+```
 
 ## Links
 
-- [MISSION.md](MISSION.md)
+- [MISSION.md](MISSION.md) — your project goals
+- [agentic-lib documentation](https://github.com/xn-intenton-z2a/agentic-lib) — full SDK docs
+- [intentïon website](https://xn--intenton-z2a.com)

package/src/seeds/zero-package.json

@@ -14,7 +14,7 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@xn-intenton-z2a/agentic-lib": "^7.1.26"
+    "@xn-intenton-z2a/agentic-lib": "^7.1.27"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.0",

package/src/workflows/agent-flow-transform.yml

@@ -11,7 +11,7 @@ concurrency: agentic-lib-main
 
 on:
   schedule:
-    - cron: "17 6,8,10,12 * * *" # 06:17, 08:17, 10:17, 12:17 UTC
+    - cron: '23 */11 * * *'
   workflow_dispatch:
     inputs:
       model: