@xn-intenton-z2a/agentic-lib 7.1.25 → 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.25",
+  "version": "7.1.27",
   "description": "Agentic-lib Agentic Coding Systems SDK powering automated GitHub workflows.",
   "type": "module",
   "scripts": {

package/src/actions/agentic-step/action.yml

@@ -13,7 +13,7 @@ inputs:
   task:
     description: >
       The task to perform. One of: resolve-issue, fix-code, transform, maintain-features,
-      maintain-library, enhance-issue, review-issue, discussions
+      maintain-library, enhance-issue, review-issue, discussions, supervise
     required: true
   config:
     description: "Path to agentic-lib.yml configuration file"

package/src/actions/agentic-step/index.js

@@ -20,6 +20,7 @@ import { maintainLibrary } from "./tasks/maintain-library.js";
 import { enhanceIssue } from "./tasks/enhance-issue.js";
 import { reviewIssue } from "./tasks/review-issue.js";
 import { discussions } from "./tasks/discussions.js";
+import { supervise } from "./tasks/supervise.js";
 
 const TASKS = {
   "resolve-issue": resolveIssue,
@@ -30,6 +31,7 @@ const TASKS = {
   "enhance-issue": enhanceIssue,
   "review-issue": reviewIssue,
   "discussions": discussions,
+  "supervise": supervise,
 };
 
 async function run() {

package/src/actions/agentic-step/tasks/supervise.js

@@ -0,0 +1,285 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// tasks/supervise.js — Supervisor orchestration via LLM
+//
+// Gathers repository context (issues, PRs, workflows, features, library, activity),
+// asks the Copilot SDK to choose multiple concurrent actions, then dispatches them.
+
+import * as core from "@actions/core";
+import { existsSync } from "fs";
+import { runCopilotTask, readOptionalFile, scanDirectory } from "../copilot.js";
+
+async function gatherContext(octokit, repo, config) {
+  const mission = readOptionalFile(config.paths.mission.path);
+  const recentActivity = readOptionalFile(config.intentionBot.intentionFilepath).split("\n").slice(-20).join("\n");
+
+  const featuresPath = config.paths.features.path;
+  const featureNames = existsSync(featuresPath)
+    ? scanDirectory(featuresPath, ".md").map((f) => f.name.replace(".md", ""))
+    : [];
+  const featuresLimit = config.paths.features.limit || 4;
+
+  const libraryPath = config.paths.library?.path || "library/";
+  const libraryNames = existsSync(libraryPath)
+    ? scanDirectory(libraryPath, ".md").map((f) => f.name.replace(".md", ""))
+    : [];
+  const libraryLimit = config.paths.library?.limit || 32;
+
+  const { data: openIssues } = await octokit.rest.issues.listForRepo({
+    ...repo,
+    state: "open",
+    per_page: 20,
+    sort: "updated",
+    direction: "desc",
+  });
+  const issuesSummary = openIssues
+    .filter((i) => !i.pull_request)
+    .map((i) => {
+      const age = Math.floor((Date.now() - new Date(i.created_at).getTime()) / 86400000);
+      const labels = i.labels.map((l) => l.name).join(", ");
+      return `#${i.number}: ${i.title} [${labels || "no labels"}] (${age}d old)`;
+    });
+
+  const { data: openPRs } = await octokit.rest.pulls.list({
+    ...repo,
+    state: "open",
+    per_page: 10,
+    sort: "updated",
+    direction: "desc",
+  });
+  const prsSummary = openPRs.map((pr) => {
+    const age = Math.floor((Date.now() - new Date(pr.created_at).getTime()) / 86400000);
+    const labels = pr.labels.map((l) => l.name).join(", ");
+    return `#${pr.number}: ${pr.title} (${pr.head.ref}) [${labels || "no labels"}] (${age}d old)`;
+  });
+
+  let workflowsSummary = [];
+  try {
+    const { data: runs } = await octokit.rest.actions.listWorkflowRunsForRepo({
+      ...repo,
+      per_page: 10,
+    });
+    workflowsSummary = runs.workflow_runs.map((r) => `${r.name}: ${r.conclusion || r.status} (${r.created_at})`);
+  } catch (err) {
+    core.warning(`Could not fetch workflow runs: ${err.message}`);
+  }
+
+  return {
+    mission,
+    recentActivity,
+    featureNames,
+    featuresLimit,
+    libraryNames,
+    libraryLimit,
+    issuesSummary,
+    prsSummary,
+    workflowsSummary,
+    schedule: config.schedule,
+    supervisor: config.supervisor,
+  };
+}
+
+function buildPrompt(ctx, agentInstructions) {
+  return [
+    "## Instructions",
+    agentInstructions,
+    "",
+    "## Mission",
+    ctx.mission || "(no mission defined)",
+    "",
+    "## Repository State",
+    `### Open Issues (${ctx.issuesSummary.length})`,
+    ctx.issuesSummary.join("\n") || "none",
+    "",
+    `### Open PRs (${ctx.prsSummary.length})`,
+    ctx.prsSummary.join("\n") || "none",
+    "",
+    `### Features (${ctx.featureNames.length}/${ctx.featuresLimit})`,
+    ctx.featureNames.join(", ") || "none",
+    "",
+    `### Library Docs (${ctx.libraryNames.length}/${ctx.libraryLimit})`,
+    ctx.libraryNames.join(", ") || "none",
+    "",
+    `### Recent Workflow Runs`,
+    ctx.workflowsSummary.join("\n") || "none",
+    "",
+    `### Recent Activity`,
+    ctx.recentActivity || "none",
+    "",
+    `### Schedule: ${ctx.schedule}, Supervisor: ${ctx.supervisor}`,
+    "",
+    "## Available Actions",
+    "Pick one or more actions. Output them in the format below.",
+    "",
+    "### Workflow Dispatches",
+    "- `dispatch:agent-flow-transform` — Pick up next issue, generate code, open PR",
+    "- `dispatch:agent-flow-maintain` — Refresh feature definitions and library docs",
+    "- `dispatch:agent-flow-review` — Close resolved issues, enhance issue criteria",
+    "- `dispatch:agent-flow-fix-code | pr-number: <N>` — Fix a failing PR",
+    "- `dispatch:agent-discussions-bot` — Proactively post in discussions",
+    "",
+    "### GitHub API Actions",
+    "- `github:create-issue | title: <text> | labels: <comma-separated>` — Create a new issue",
+    "- `github:label-issue | issue-number: <N> | labels: <comma-separated>` — Add labels to an issue",
+    "- `github:close-issue | issue-number: <N>` — Close an issue",
+    "",
+    "### Communication",
+    "- `respond:discussions | message: <text> | discussion-url: <url>` — Reply via discussions bot",
+    "- `nop` — No action needed this cycle",
+    "",
+    "## Output Format",
+    "Respond with EXACTLY this structure:",
+    "```",
+    "[ACTIONS]",
+    "action-name | param: value | param: value",
+    "[/ACTIONS]",
+    "[REASONING]",
+    "Why you chose these actions...",
+    "[/REASONING]",
+    "```",
+  ].join("\n");
+}
+
+function parseActions(content) {
+  const actionsMatch = content.match(/\[ACTIONS\]([\s\S]*?)\[\/ACTIONS\]/);
+  if (!actionsMatch) return [];
+
+  return actionsMatch[1]
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith("#"))
+    .map((line) => {
+      const parts = line.split("|").map((p) => p.trim());
+      const action = parts[0];
+      const params = {};
+      for (const part of parts.slice(1)) {
+        const colonIdx = part.indexOf(":");
+        if (colonIdx > 0) {
+          params[part.substring(0, colonIdx).trim()] = part.substring(colonIdx + 1).trim();
+        }
+      }
+      return { action, params };
+    });
+}
+
+function parseReasoning(content) {
+  const match = content.match(/\[REASONING\]([\s\S]*?)\[\/REASONING\]/);
+  return match ? match[1].trim() : "";
+}
+
+async function executeDispatch(octokit, repo, actionName, params) {
+  const workflowFile = actionName.replace("dispatch:", "") + ".yml";
+  const inputs = {};
+  if (params["pr-number"]) inputs["pr-number"] = params["pr-number"];
+  core.info(`Dispatching workflow: ${workflowFile}`);
+  await octokit.rest.actions.createWorkflowDispatch({ ...repo, workflow_id: workflowFile, ref: "main", inputs });
+  return `dispatched:${workflowFile}`;
+}
+
+async function executeCreateIssue(octokit, repo, params) {
+  const title = params.title || "Untitled issue";
+  const labels = params.labels ? params.labels.split(",").map((l) => l.trim()) : ["automated"];
+  core.info(`Creating issue: ${title}`);
+  const { data: issue } = await octokit.rest.issues.create({ ...repo, title, labels });
+  return `created-issue:#${issue.number}`;
+}
+
+async function executeLabelIssue(octokit, repo, params) {
+  const issueNumber = Number(params["issue-number"]);
+  const labels = params.labels ? params.labels.split(",").map((l) => l.trim()) : [];
+  if (issueNumber && labels.length > 0) {
+    core.info(`Labelling issue #${issueNumber}: ${labels.join(", ")}`);
+    await octokit.rest.issues.addLabels({ ...repo, issue_number: issueNumber, labels });
+    return `labelled-issue:#${issueNumber}`;
+  }
+  return "skipped:label-issue-missing-params";
+}
+
+async function executeCloseIssue(octokit, repo, params) {
+  const issueNumber = Number(params["issue-number"]);
+  if (issueNumber) {
+    core.info(`Closing issue #${issueNumber}`);
+    await octokit.rest.issues.update({ ...repo, issue_number: issueNumber, state: "closed" });
+    return `closed-issue:#${issueNumber}`;
+  }
+  return "skipped:close-issue-missing-number";
+}
+
+async function executeRespondDiscussions(octokit, repo, params) {
+  const message = params.message || "";
+  const url = params["discussion-url"] || "";
+  if (message) {
+    core.info(`Dispatching discussions bot with response: ${message.substring(0, 100)}`);
+    await octokit.rest.actions.createWorkflowDispatch({
+      ...repo,
+      workflow_id: "agent-discussions-bot.yml",
+      ref: "main",
+      inputs: {},
+    });
+    return `respond-discussions:${url || "no-url"}`;
+  }
+  return "skipped:respond-no-message";
+}
+
+const ACTION_HANDLERS = {
+  "github:create-issue": executeCreateIssue,
+  "github:label-issue": executeLabelIssue,
+  "github:close-issue": executeCloseIssue,
+  "respond:discussions": executeRespondDiscussions,
+};
+
+async function executeAction(octokit, repo, action, params) {
+  if (action.startsWith("dispatch:")) return executeDispatch(octokit, repo, action, params);
+  if (action === "nop") return "nop";
+  const handler = ACTION_HANDLERS[action];
+  if (handler) return handler(octokit, repo, params);
+  core.warning(`Unknown action: ${action}`);
+  return `unknown:${action}`;
+}
+
+/**
+ * Supervisor task: gather context, ask LLM to choose actions, execute them.
+ *
+ * @param {Object} context - Task context from index.js
+ * @returns {Promise<Object>} Result with outcome, tokensUsed, model
+ */
+export async function supervise(context) {
+  const { octokit, repo, config, instructions, model } = context;
+
+  const ctx = await gatherContext(octokit, repo, config);
+  const agentInstructions = instructions || "You are the supervisor. Decide what actions to take.";
+  const prompt = buildPrompt(ctx, agentInstructions);
+
+  const { content, tokensUsed } = await runCopilotTask({
+    model,
+    systemMessage:
+      "You are the supervisor of an autonomous coding repository. Your job is to advance the mission by choosing which workflows to dispatch and which GitHub actions to take. Pick multiple actions when appropriate. Be strategic — consider what's already in progress, what's blocked, and what will make the most impact.",
+    prompt,
+    writablePaths: [],
+  });
+
+  const actions = parseActions(content);
+  const reasoning = parseReasoning(content);
+
+  core.info(`Supervisor reasoning: ${reasoning.substring(0, 200)}`);
+  core.info(`Supervisor chose ${actions.length} action(s)`);
+
+  const results = [];
+  for (const { action, params } of actions) {
+    try {
+      const result = await executeAction(octokit, repo, action, params);
+      results.push(result);
+      core.info(`Action result: ${result}`);
+    } catch (err) {
+      core.warning(`Action ${action} failed: ${err.message}`);
+      results.push(`error:${action}:${err.message}`);
+    }
+  }
+
+  return {
+    outcome: actions.length === 0 ? "nop" : `supervised:${actions.length}-actions`,
+    tokensUsed,
+    model,
+    details: `Actions: ${results.join(", ")}\nReasoning: ${reasoning.substring(0, 300)}`,
+  };
+}

package/src/agents/agent-supervisor.md

@@ -0,0 +1,30 @@
+You are the supervisor of an autonomous coding repository. Your job is to advance the mission by strategically choosing which workflows to dispatch and which GitHub actions to take.
+
+## Decision Framework
+
+1. **Check what's already in progress** — don't duplicate work. If a transform is running, don't dispatch another.
+2. **Prioritise unblocking** — fix failing PRs before starting new features. Close resolved issues to free capacity.
+3. **Balance the pipeline** — maintain a healthy mix of feature work, maintenance, and review.
+4. **Respect limits** — don't create issues beyond the WIP limit. Don't dispatch workflows that will fail due to missing prerequisites.
+5. **Be strategic about timing** — if the schedule is hourly, you can afford to spread work across cycles. If daily, batch more aggressively.
+
+## When to use each action
+
+- **dispatch:agent-flow-transform** — When there are open issues ready to work on and no transform is currently running.
+- **dispatch:agent-flow-maintain** — When features or library docs are below their limits, or haven't been refreshed recently.
+- **dispatch:agent-flow-review** — When there are open automated issues that might be resolved, or issues that need better acceptance criteria.
+- **dispatch:agent-flow-fix-code** — When a specific PR has failing checks. Always include the pr-number.
+- **dispatch:agent-discussions-bot** — When you want to proactively engage in discussions or respond to a user request.
+- **github:create-issue** — When you identify a gap between the mission and current features. Always include a descriptive title and relevant labels.
+- **github:label-issue** — When an issue needs better categorisation for prioritisation.
+- **github:close-issue** — When an issue is clearly resolved or no longer relevant.
+- **respond:discussions** — When replying to a user request that came through the discussions bot. Include the discussion URL and a clear message.
+- **nop** — When everything is running smoothly and no intervention is needed.
+
+## Guidelines
+
+- Pick multiple actions when appropriate — concurrent work is encouraged.
+- Always explain your reasoning — this helps future cycles understand the trajectory.
+- When a user has made a request via discussions, prioritise responding to it.
+- Don't dispatch the same workflow twice in one cycle.
+- If recent workflow runs show failures, investigate before dispatching more work.

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.25"
+    "@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: