# Set up Inwoven in this repo Inwoven is a backlog board that reads plain files in the user's GitHub repo. You create the files and push them. The user then connects the repo in the browser. Follow the steps in order. Do not ask the user for anything, except where a step says so. ## 1. Create docs/product/backlog.md If the file exists, read it, keep every row, and go to step 2. Otherwise create it: - Start with the front matter. Set `updated` to today's date. - Write the table header and the separator row exactly as in the example. - Write one row per item. Row order is priority: the first row is the first item to work. - Each row has five cells: Item (PBI), Core Job, Context, Status and Driver. - The Driver cell holds the name of the person who drives the item, never an agent's name. Leave it empty unless the user names a person. Use the name the Driver column already holds for that person. - The first cell is the id, a dot, a space and the title, for example `A101. Title`. The id is one letter from `ABCDEFGHJKLMNPRSTUVWXYZ` and three digits from 100 to 999. Pick it at random. Each id is unique in the file and is never reused. - The title is at most 80 characters. The Context is at most 280 characters. Keep the pipe character out of every cell. - Status is empty, `To Do`, `In Progress` or `Done`. An empty cell means To Do. Tags follow `
` in the Status cell, for example `In Progress
Waiting on: legal review`. - Use the user's real work in the rows. If you cannot find it in the repo, ask the user for the top items. Do not leave the example rows in the file. File: `docs/product/backlog.md` ```markdown --- title: "My product backlog" updated: 2026-11-03 --- # My product backlog | Item (PBI) | Core Job | Context | Status | Driver | |---|---|---|---|---| | A101. Let a visitor book a demo from the home page | Book a demo without writing an email | The form asks for a name and an email. It sends a confirmation. | In Progress | Ana | | K417. Show the price on the pricing page | Know the price before talking to sales | | | Ana | | M238. Fix the broken link in the welcome email | | Reported by a customer on Monday. | Done | Ben | ``` A real file is at https://backlog.works/backlog.md. It is Inwoven's own backlog. ## 2. Add goals and impact maps, optional Do this only if the user has a goal to record. The board works without these two files. `docs/product/goals.md` holds the goals. One goal is Now. One may be Next and one may be Later, in that order. The Set date is required for Now and empty for Next and Later. The goal and the measure are each at most 200 characters. Closed and Outcome are empty until the goal is closed as Achieved, Missed or Dropped; a closed goal keeps its row and the horizon it left. Every goal has a permanent id in the last column, `goal-1`, `goal-2` and so on: a new goal takes the highest number plus one, and no number is ever reused. File: `docs/product/goals.md` ```markdown --- title: "My product goals" updated: 2026-11-03 --- # Product Goal | Goal | Measure | Horizon | Set | Closed | Outcome | Id | |---|---|---|---|---|---|---| | Visitors book demos without help | 20 demo bookings in a month | Now | 2026-11-03 | | | goal-1 | | Customers renew without a call | Renewal rate above 80% | Next | | | | goal-2 | ``` `docs/product/impact.md` holds one map per goal. Each `## ` heading is the goal text exactly as in goals.md, and the line under it is the goal's id as a comment, ``: the map belongs to its goal, not to Now, Next or Later, and a closed goal's map stays in the file as history. The list has three levels, indented by two spaces. Level one is who must act differently. Level two is how they act differently. Level three is an item id from backlog.md or `GAP: ` and a short text for work that is not an item yet. Each text is at most 80 characters. File: `docs/product/impact.md` ```markdown --- title: "My product impact maps" updated: 2026-11-03 --- # Impact maps ## Visitors book demos without help - Visitors - Book a demo from the home page - A101 - Know the price before they ask - K417 - GAP: Compare plans on one page ``` ## 3. Add the AGENTS.md block Append the block below to `AGENTS.md` in the repo root. Create the file if it does not exist. If the file already has a `## Product files` heading, do not add the block again. Change the path in the block if the files are not in `docs/product/`. Append to: `AGENTS.md` ```markdown ## Product files Our product files are in docs/product/. Change the path if yours differ. - backlog.md: one row per item. Row order is priority. - goals.md: the goals, each with a measure and a horizon: Now, Next or Later. - impact.md: one map per goal. It lists who must act differently, how, and the item ids that cause it. - learnings.md: lessons the team approved, one line each. A lesson expires after 90 days unless a check enforces it. ## Working an item - Work the highest item whose Status is In Progress. Start a To Do item only when the person who owns the backlog asks. - Before you start, find the item's id in impact.md and read its goal, actor and change. If the id is not there, say so. - Read learnings.md before you start. When you finish an item, you may propose one lesson as a table row; write it only after the person says yes. - Status is To Do, In Progress or Done. An empty Status cell means To Do. Tags follow `
`, such as Ready, Waiting on:, Due:, Accepted: and Reopened. - If an item is blocked, add `Waiting on: ` as a tag. - Never mark an item Done, add Accepted or Reopened tags, reorder rows or delete items. The person accepts and orders. - Keep backlog.md valid: keep the header, five cells per row and every id. A title is at most 80 characters. ``` If the repo has a `CLAUDE.md`, make sure it has a line that says `@AGENTS.md`. Add the line if it is missing. ## 4. Install the Inwoven skill in the repo The Inwoven skill tells an agent how to read and edit these files. You install it in the repo, so every teammate and every cloud agent gets it. Run this guide again to update the skill. 1. Fetch https://github.com/priaby/inwoven into a temporary folder outside the repo. For example, run `git clone --depth 1 https://github.com/priaby/inwoven "$(mktemp -d)/inwoven"`. If git is missing, download and unpack https://codeload.github.com/priaby/inwoven/tar.gz/HEAD instead. 2. Copy the `skills/inwoven/` folder from the fetch to `.claude/skills/inwoven/` in the repo. Claude Code loads project skills from there. 3. Copy the same folder to `.agents/skills/inwoven/` in the repo. Codex and Cursor load project skills from there. 4. If one of these folders already exists, delete it first and copy the fetched folder in its place. Do not merge the two. This is how the skill updates. 5. Delete the temporary folder. ## 5. Create docs/product/learnings.md The block from step 3 tells agents to read this file. Run this command in the repo root: ```sh python3 .agents/skills/inwoven/scripts/inwoven.py init learnings --root docs/product ``` It creates the file with a table header and no rows. It keeps a file that exists. Do not write a lesson now: a lesson is added only after the user approves it. If the product files are not in `docs/product/`, pass their folder to `--root`. ## 6. Commit and push Commit only these files with a clear message, for example `docs: add Inwoven product files`: the files in `docs/product/`, `AGENTS.md`, `CLAUDE.md` if you changed it, `.claude/skills/inwoven/` and `.agents/skills/inwoven/`. Push to the branch the user will connect, usually the default branch. Inwoven reads the files from GitHub, so an unpushed commit is not visible. ## 7. Tell the user the one step left You cannot sign in or connect GitHub for the user. Say in one sentence that the Inwoven skill is now installed in the repo. Say in one more sentence that your agents now propose a lesson when they finish an item, and keep it in `docs/product/learnings.md` only after the user says yes. Then tell them this, in your own words: 1. Open https://backlog.works and sign in. Inwoven emails you a six-digit code. 2. Create a product on the Account page if you have none. 3. Open Settings, then Storage, and select Connect next to GitHub. 4. Select Open GitHub, allow the Inwoven app, and choose this repository. 5. Choose the branch and the file `docs/product/backlog.md`, then select Check the file. 6. Select Use the repo file. After that, the board shows your backlog. When you edit these files and push, the board updates. When you reorder items on the board, Inwoven commits the change to the file.