The same API, the next feature, started from Rally and SharePoint.

The hello-world run started from a Slack message. Real teams start from a Rally feature with accepted stories and a product spec in SharePoint. AI-DLC 2.11 reads only files inside the workspace, so the team snapshots both into the workspace, commits them, and names them in the request. You start from that committed workspace: one git clone of the rally-feature branch. This page shows exactly what changes, with real input files and real aidlc output. It does not replay an AI run: what Claude will do at each gate is labelled expected.

3stories in Rally feature F1187

1clone: everything already in place

expressstill the right profile

1conflict between story and spec, on purpose

0live connections needed today

2new team steps: snapshot before, write back after

What changes compared with the hello-world run

	Hello-world run (request age)	This feature (reviewer queue filters)
Start from	The starter code repo, plus the team files downloaded by hand	One clone: `aidlc-java-workspace`, branch `rally-feature`, with the finished hello-world run and the inputs already committed
Input	A Slack message, pasted into `docs-in/request.md`	A Rally feature + 3 stories, exported to `docs-in/rally/F1187-…md`; a SharePoint spec, onboarded into `knowledge/`
Who wrote the requirement	Claude, from the message, at Requirements Analysis	Product already wrote stories and acceptance criteria. Claude turns them into numbered requirements that cite the story IDs
Profile	`express`: 10 of 33 stages	`express` again: one repo, stories accepted. It skips User Stories (2.4) and Units Generation (2.7), which is right: Rally already holds the stories
Reverse engineering	Full scan of the repo	The codekb from the last run is kept, but it is a scan of v1.0.2: at v1.1.0 `aidlc engine workspace codekb-scope-diff --repo priorauth-api` reports it STALE, so expect a rescan of what changed (the `aging` package)
Team steps	Branch, commit, PR, commit the record	The same, plus snapshot the inputs before `/aidlc` and write back to Rally after the PR
New workspace files	none	`docs-in/rally/`, `docs-in/sharepoint/`, `scripts/export-rally.py`, `knowledge/documents/` + `knowledge/documentkb/`, a few lines in `CLAUDE.md`

Why snapshots, not a live connection. The record has to say which version of the stories and the spec were approved. A Rally item or a SharePoint page can change tomorrow; a committed file cannot. Live connections (step 9) are for looking things up and writing back, not for the run's inputs.

Inputssteps 1–4 · your shell and editor · about 15 minutes

yours, not the tool

Clone the starter workspace at the rally-feature branch

Everything this feature needs is already committed on one branch: the finished hello-world run, the Rally export, the onboarded spec and the team's input rules. You clone it, let AI-DLC set up its files and pull in the code repo, and start a branch for the change from v1.1.0, where the hello-world run left the code.

Kiran · Wed 14 Oct, 09:15

You type PowerShellTerminal (macOS)

mkdir C:\work -Force | Out-Null
cd C:\work
git clone -b rally-feature https://github.com/varasrinivas/aidlc-java-workspace.git java-workspace
cd java-workspace
aidlc config --harness claude
aidlc system workspace-sync
git -C priorauth-api switch -c request-filters v1.1.0

mkdir -p ~/work && cd ~/work
git clone -b rally-feature https://github.com/varasrinivas/aidlc-java-workspace.git java-workspace
cd java-workspace
aidlc config --harness claude
aidlc system workspace-sync
git -C priorauth-api switch -c request-filters v1.1.0

You see real output, abridged · AI-DLC 2.11.0

Cloning into 'java-workspace'...
configured …\java-workspace for Claude Code 2.11.0; next: open Claude Code in this project …
aidlc workspace-sync: reconciling …\java-workspace against repos.json (1 repo(s))
  staging clone priorauth-api from https://github.com/varasrinivas/aidlc-priorauth-api.git (branch main) ...
  ✓ cloned priorauth-api on 'main'
  ✓ .gitignore managed block → 1 child dir(s)
  ✓ aidlc.code-workspace → 1 child root(s)
✓ workspace in sync
Switched to a new branch 'request-filters'

On disk now

java-workspace/                                   branch rally-feature of aidlc-java-workspace
  CLAUDE.md                                       team rules + the Rally/SharePoint input rules (step 4)
  repos.json                                      priorauth-api, cloned from the public starter repo
  docs-in/rally/F1187-reviewer-queue-filters.md   the export AI-DLC reads (step 2)
  docs-in/rally/F1187.json                        the Rally API responses it was made from
  docs-in/sharepoint/Reviewer-Queue-API-Spec.md   the spec, as markitdown converted it from Word
  scripts/export-rally.py                         turns the API responses into the .md
  aidlc/spaces/default/knowledge/                 the spec, onboarded (step 3)
  aidlc/spaces/default/codekb/priorauth-api/      the hello-world scan, at v1.0.2
  aidlc/spaces/default/intents/261013-…/          the hello-world run: status complete
  priorauth-api/                                  cloned by workspace-sync; branch request-filters at v1.1.0

You see the branch's history: the story so far

$ git log --oneline
299f894 F1187 inputs: Rally export, SharePoint spec onboarded, input rules
f0c0c0f intent 261013-request-age-api: complete (PR #58, v1.1.0)
97693a3 Workspace for priorauth-api: team rules, repo list, verify scripts

Why a workspace repoAI-DLC runs from the folder around the code. Committing that folder is how a team shares the record, the codekb and the inputs; repos.json brings the code repo back on every machine.

Why v1.1.0workspace-sync checks out main of the starter, which is v1.0.2 (before the hello-world change). This feature builds on the age fields, so the branch starts from the tag v1.1.0.

DoctorUntil you start Claude Code here once, aidlc doctor reports "Hooks have never executed although this workflow has progressed 10 stages": the finished run came from another machine. It clears when the hooks run in your first claude session.

already done · check it

The Rally feature, already exported to a file AI-DLC can read

Kiran exported the feature before committing it. Re-run the export yourself: it rewrites the Markdown from the saved API response, and git status printing nothing proves the committed file is exactly what the script produces. Later, the same script calls Rally with a read-only key.

Kiran · 09:18

You type PowerShell, inside java-workspaceTerminal (macOS), inside java-workspace

python scripts\export-rally.py --from-json docs-in\rally\F1187.json --out docs-in\rally\F1187-reviewer-queue-filters.md
git status --short docs-in

python3 scripts/export-rally.py --from-json docs-in/rally/F1187.json --out docs-in/rally/F1187-reviewer-queue-filters.md
git status --short docs-in

You see real output

wrote docs-in\rally\F1187-reviewer-queue-filters.md (58 lines)wrote docs-in/rally/F1187-reviewer-queue-filters.md (58 lines)
(git status prints nothing: identical)

docs-in/rally/F1187-reviewer-queue-filters.mdwhat the run reads · real file

# F1187 Reviewer queue filters

> Snapshot of a Rally feature and its user stories, written by `scripts/export-rally.py` (offline, from F1187.json).
> Rally is the source of truth: refresh this file before `/aidlc`, and cite the story IDs (US…) in requirements.

| Field | Value |
|---|---|
| Epic | E212 Reviewer screen v2 |
| State | Ready |
| Owner | Ravi Menon |
| Release | 2026.Q4 R2 |
| Last updated in Rally | 2026-10-14 |
| Stories | 3 |

## Feature description

Reviewers now see each request's age and over-limit flag (F1162, delivered in priorauth-api 1.1.0). The list is still one long queue across every health plan, so a reviewer who covers one plan, or who is clearing over-limit requests first, scrolls past rows they will not touch.

Let the screen ask the API for a narrower list: by tenant, by status, and only the over-limit rows. The screen change is a separate feature (F1190).

## User stories

### US5120 Filter the pending list by tenant

Schedule state: Defined · Estimate: 2 · Owner: Kiran Rao

As a reviewer who covers one health plan, I want the pending list for my tenant only, so that I don't scroll past other plans' requests.

**Note:** the sample export has only TX-01 today. Add a second tenant (NM-02) to the sample data so this story can be tested.

**Acceptance criteria**

- `GET /requests/pending?tenant=TX-01` returns only TX-01 rows, oldest first.
- Without `tenant`, every tenant is returned, as today.
- A tenant with no pending requests, or one we don't know, returns an empty list (200).

### US5121 Filter the pending list by status

Schedule state: Defined · Estimate: 1 · Owner: Kiran Rao

As a reviewer, I want to see only the requests waiting on me (`IN_REVIEW`) or only the ones waiting on the provider (`PENDED`), so that I work one kind at a time.

**Acceptance criteria**

- `?status=PENDED` and `?status=IN_REVIEW` return only rows with that status.
- Any other value, including a status that is not pending such as `APPROVED`, returns 400 with a message naming the allowed values.

### US5122 Show only the over-limit requests

Schedule state: Defined · Estimate: 2 · Owner: Kiran Rao

As a nurse manager, I want the list of requests that are over the business-day limit, so that the team clears them first.

**Acceptance criteria**

- `?overLimit=true` returns only rows whose `overLimit` is true; `?overLimit=false` returns the others.
- The flag is computed for the same `asOf` date as the rest of the response.
- Filters combine: `?tenant=TX-01&overLimit=true` returns rows that match both.

docs-in/rally/F1187.jsonwhat Rally's API returns, trimmed

{
 "_comment": "Two Rally WSAPI v2.0 query responses, trimmed to the fields export-rally.py fetches. Hand-written course data standing in for a real export: 'feature' answers GET portfolioitem/feature?query=(FormattedID = \"F1187\"), 'stories' answers GET hierarchicalrequirement?query=(PortfolioItem.FormattedID = \"F1187\"). c_AcceptanceCriteria is a custom field: Rally has no standard acceptance-criteria field, and its name varies by workspace.",
 "feature": {
 "QueryResult": {
 "_rallyAPIMajor": "2",
 "_rallyAPIMinor": "0",
 "Errors": [],
 "Warnings": [],
 "TotalResultCount": 1,
 "StartIndex": 1,
 "PageSize": 200,
 "Results": [
 {
 "_type": "PortfolioItem/Feature",
 "FormattedID": "F1187",
 "Name": "Reviewer queue filters",
 "Description": "Reviewers now see each request's age and over-limit flag (F1162, delivered in priorauth-api 1.1.0). The list is still one long queue across every health plan, so a reviewer who covers one plan, or who is clearing over-limit requests first, scrolls past rows they will not touch.Let the screen ask the API for a narrower list: by tenant, by status, and only the over-limit rows. The screen change is a separate feature (F1190).",
 "State": { "_refObjectName": "Ready" },
 "Parent": { "_type": "PortfolioItem/Epic", "FormattedID": "E212", "_refObjectName": "Reviewer screen v2" },
 "Owner": { "_refObjectName": "Ravi Menon" },
 "Release": { "_refObjectName": "2026.Q4 R2" },
 "LastUpdateDate": "2026-10-14T10:05:00.000Z"
 }
 ]
 }
 },
 "stories": {
 "QueryResult": {
 "_rallyAPIMajor": "2",
 "_rallyAPIMinor": "0",
 "Errors": [],
 "Warnings": [],
 "TotalResultCount": 3,
 "StartIndex": 1,
 "PageSize": 200,
 "Results": [
 {
 "_type": "HierarchicalRequirement",
 "FormattedID": "US5120",
 "Name": "Filter the pending list by tenant",
 "Description": "As a reviewer who covers one health plan, I want the pending list for my tenant only, so that I don't scroll past other plans' requests.Note: the sample export has only TX-01 today. Add a second tenant (NM-02) to the sample data so this story can be tested.",
 "c_AcceptanceCriteria": "<ul><li><code>GET /requests/pending?tenant=TX-01</code> returns only TX-01 rows, oldest first.</li><li>Without <code>tenant</code>, every tenant is returned, as today.</li><li>A tenant with no pending requests, or one we don't know, returns an empty list (200).</li></ul>",
 "ScheduleState": "Defined",
 "PlanEstimate": 2.0,
 "Owner": { "_refObjectName": "Kiran Rao" },
 "PortfolioItem": { "_type": "PortfolioItem/Feature", "FormattedID": "F1187" }
 },
 {
 "_type": "HierarchicalRequirement",
 "FormattedID": "US5121",
 "Name": "Filter the pending list by status",
 "Description": "As a reviewer, I want to see only the requests waiting on me (<code>IN_REVIEW</code>) or only the ones waiting on the provider (<code>PENDED</code>), so that I work one kind at a time.",
 "c_AcceptanceCriteria": "<ul><li><code>?status=PENDED</code> and <code>?status=IN_REVIEW</code> return only rows with that status.</li><li>Any other value, including a status that is not pending such as <code>APPROVED</code>, returns 400 with a message naming the allowed values.</li></ul>",
 "ScheduleState": "Defined",
 "PlanEstimate": 1.0,
 "Owner": { "_refObjectName": "Kiran Rao" },
 "PortfolioItem": { "_type": "PortfolioItem/Feature", "FormattedID": "F1187" }
 },
 {
 "_type": "HierarchicalRequirement",
 "FormattedID": "US5122",
 "Name": "Show only the over-limit requests",
 "Description": "As a nurse manager, I want the list of requests that are over the business-day limit, so that the team clears them first.",
 "c_AcceptanceCriteria": "<ul><li><code>?overLimit=true</code> returns only rows whose <code>overLimit</code> is true; <code>?overLimit=false</code> returns the others.</li><li>The flag is computed for the same <code>asOf</code> date as the rest of the response.</li><li>Filters combine: <code>?tenant=TX-01&amp;overLimit=true</code> returns rows that match both.</li></ul>",
 "ScheduleState": "Defined",
 "PlanEstimate": 2.0,
 "Owner": { "_refObjectName": "Kiran Rao" },
 "PortfolioItem": { "_type": "PortfolioItem/Feature", "FormattedID": "F1187" }
 }
 ]
 }
 }
}

scripts/export-rally.pystandard library only

#!/usr/bin/env python3
"""
Export one Rally feature and its user stories to a Markdown file that AI-DLC can read.

AI-DLC reads only files inside the workspace, so the team snapshots the feature before
`/aidlc` and commits the snapshot with the run's record: the record then points at the exact
version of the stories that were approved, not at a live item that may change tomorrow.

# offline: render a saved WSAPI response (how the course file was produced)
    python scripts/export-rally.py --from-json docs-in/rally/F1187.json --out docs-in/rally/F1187-reviewer-queue-filters.md

# live: query Rally with a read-only API key (RALLY_API_KEY), save the raw JSON too
    python scripts/export-rally.py --feature F1187 --save-json docs-in/rally/F1187.json --out docs-in/rally/F1187-reviewer-queue-filters.md

Live mode follows Rally's documented Web Services API v2.0 (base URL, `zsessionid` header,
`query`/`fetch`/`order`/`pagesize`), but it has NOT been run against a Rally subscription for
this course. Check the acceptance-criteria field name in your workspace: Rally has no standard
one, so it is a custom `c_` field (default here: c_AcceptanceCriteria; --ac-field to change).

Standard library only. Python 3.9+.
"""
import argparse
import json
import os
import sys
import urllib.parse
import urllib.request
from html.parser import HTMLParser
from pathlib import Path

DEFAULT_URL = "https://rally1.rallydev.com/slm/webservice/v2.0"
FEATURE_FIELDS = "FormattedID,Name,Description,State,Parent,Owner,Release,LastUpdateDate"
STORY_FIELDS = "FormattedID,Name,Description,ScheduleState,PlanEstimate,Owner,PortfolioItem"

class HtmlToMarkdown(HTMLParser):
    """Rally rich-text fields are HTML; keep paragraphs, lists, bold and code, drop the rest."""

def __init__(self):
        super().__init__(convert_charrefs=True)
        self.out = []

def handle_starttag(self, tag, attrs):
        if tag == "li":
            self.out.append("\n- ")
        elif tag in ("b", "strong"):
            self.out.append("**")
        elif tag == "code":
            self.out.append("`")
        elif tag == "br":
            self.out.append("\n")

def handle_endtag(self, tag):
        if tag in ("p", "ul", "ol", "div"):
            self.out.append("\n\n")
        elif tag in ("b", "strong"):
            self.out.append("**")
        elif tag == "code":
            self.out.append("`")

def handle_data(self, data):
        self.out.append(data)

def md(html_text):
    parser = HtmlToMarkdown()
    parser.feed(html_text or "")
    lines = [line.rstrip() for line in "".join(parser.out).split("\n")]
    text = "\n".join(lines)
    while "\n\n\n" in text:
        text = text.replace("\n\n\n", "\n\n")
    return text.strip()

def ref_name(value):
    """A WSAPI reference is an object; show its FormattedID and name when present."""
    if not value:
        return ""
    if isinstance(value, str):
        return value
    fid, name = value.get("FormattedID"), value.get("_refObjectName")
    return f"{fid} {name}".strip() if fid and name else (fid or name or "")

def results(response, what):
    qr = response.get("QueryResult", {})
    if qr.get("Errors"):
        sys.exit(f"Rally returned errors for {what}: {qr['Errors']}")
    return qr.get("Results", [])

def get(base, path, params, key):
    url = f"{base}/{path}?{urllib.parse.urlencode(params)}"
    req = urllib.request.Request(url, headers={"zsessionid": key, "Accept": "application/json"})
    try:
        with urllib.request.urlopen(req, timeout=30) as resp:
            return json.load(resp)
    except urllib.error.HTTPError as e:
        hint = " Check RALLY_API_KEY (Rally keys start with an underscore)." if e.code in (401, 403) else ""
        sys.exit(f"Rally answered {e.code} {e.reason} for {path}.{hint}")
    except urllib.error.URLError as e:
        sys.exit(f"Cannot reach Rally at {base}: {e.reason}. Check RALLY_URL and your network.")

def fetch_live(feature_id, ac_field):
    key = os.environ.get("RALLY_API_KEY")
    if not key:
        sys.exit("RALLY_API_KEY is not set. Create a read-only API key in Rally and export it; never commit it.")
    base = os.environ.get("RALLY_URL", DEFAULT_URL).rstrip("/")
    feature = get(base, "portfolioitem/feature",
                  {"query": f'(FormattedID = "{feature_id}")', "fetch": FEATURE_FIELDS}, key)
    stories = get(base, "hierarchicalrequirement",
                  {"query": f'(PortfolioItem.FormattedID = "{feature_id}")',
                   "fetch": f"{STORY_FIELDS},{ac_field}", "order": "FormattedID", "pagesize": 200}, key)
    return {"feature": feature, "stories": stories}

def render(data, ac_field, source):
    features = results(data["feature"], "the feature")
    if len(features) != 1:
        sys.exit(f"expected exactly one feature, got {len(features)}")
    f = features[0]
    stories = sorted(results(data["stories"], "the stories"), key=lambda s: s["FormattedID"])

out = [f"# {f['FormattedID']} {f['Name']}", ""]
    out.append(f"> Snapshot of a Rally feature and its user stories, written by `scripts/export-rally.py` ({source}).")
    out.append("> Rally is the source of truth: refresh this file before `/aidlc`, and cite the story IDs (US…) in requirements.")
    out.append("")
    out += ["| Field | Value |", "|---|---|"]
    for label, value in [("Epic", ref_name(f.get("Parent"))), ("State", ref_name(f.get("State"))),
                         ("Owner", ref_name(f.get("Owner"))), ("Release", ref_name(f.get("Release"))),
                         ("Last updated in Rally", (f.get("LastUpdateDate") or "")[:10]),
                         ("Stories", str(len(stories)))]:
        if value:
            out.append(f"| {label} | {value} |")
    out += ["", "## Feature description", "", md(f.get("Description")), "", "## User stories", ""]
    for s in stories:
        estimate = s.get("PlanEstimate")
        estimate = f"{estimate:g}" if isinstance(estimate, (int, float)) else "—"
        out += [f"### {s['FormattedID']} {s['Name']}", ""]
        out.append(f"Schedule state: {s.get('ScheduleState', '—')} · Estimate: {estimate} · Owner: {ref_name(s.get('Owner')) or '—'}")
        out += ["", md(s.get("Description")), "", "**Acceptance criteria**", ""]
        criteria = md(s.get(ac_field))
        out.append(criteria if criteria else f"(none: the `{ac_field}` field is empty or missing)")
        out.append("")
    return "\n".join(out).rstrip() + "\n"

def main():
    ap = argparse.ArgumentParser(description="Export a Rally feature and its user stories to Markdown.")
    src = ap.add_mutually_exclusive_group(required=True)
    src.add_argument("--feature", help="FormattedID of the feature to fetch live, e.g. F1187")
    src.add_argument("--from-json", type=Path, help="render a saved response instead of calling Rally")
    ap.add_argument("--ac-field", default="c_AcceptanceCriteria", help="custom field that holds acceptance criteria")
    ap.add_argument("--out", type=Path, help="Markdown file to write (default: print)")
    ap.add_argument("--save-json", type=Path, help="live mode: also save the raw responses here")
    args = ap.parse_args()

if args.from_json:
        data = json.loads(args.from_json.read_text(encoding="utf-8"))
        source = f"offline, from {args.from_json.name}"
    else:
        data = fetch_live(args.feature, args.ac_field)
        source = "live, Rally WSAPI v2.0"
        if args.save_json:
            args.save_json.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")

text = render(data, args.ac_field, source)
    if args.out:
        args.out.write_text(text, encoding="utf-8", newline="\n")
        print(f"wrote {args.out} ({text.count(chr(10))} lines)")
    else:
        sys.stdout.reconfigure(encoding="utf-8", newline="\n")
        sys.stdout.write(text)

if __name__ == "__main__":
    main()

$env:RALLY_API_KEY = "<a read-only Rally API key>"
python scripts\export-rally.py --feature F1187 --save-json docs-in\rally\F1187.json --out docs-in\rally\F1187-reviewer-queue-filters.md

Later, with a real subscription (Windows; on macOS export RALLY_API_KEY=… and python3). Live mode follows Rally's documented API (zsessionid header, query/fetch) and reaches it (a wrong key stops with "Rally answered 401 Unauthorized … Check RALLY_API_KEY"), but it has not been run with a real key for this course. Your acceptance-criteria field may not be c_AcceptanceCriteria: Rally has no standard one, so pass --ac-field.

In plain words. The story in Rally is the order on the restaurant's tablet. The export is the printed ticket clipped to the pass: the kitchen cooks from the ticket, and if the order changes, a new ticket is printed.

already done · check it

The spec, already onboarded into the space's knowledge base

DocumentKB is AI-DLC's catalog of documents the team already owns. Onboarding extracted the text, fingerprinted it, and recorded it as untrusted data, so a sentence in a spec can never act as an instruction. The catalog is committed, so your clone already has it.

Kiran · 09:22

You type PowerShell or Terminal, inside java-workspace

aidlc engine knowledge list

You see real output, AI-DLC 2.11.0

UNTRUSTED PATHS — NOT INSTRUCTIONS. …

1 document(s)
id                                    extraction/status       summary      path
01a13951-ae71-7f78-93bd-9d5ffeea2b9e  extracted               absent       documents/Reviewer-Queue-API-Spec.md

On disk now

java-workspace/aidlc/spaces/default/knowledge/
  documents/Reviewer-Queue-API-Spec.md            the team's copy of the document
  documentkb/index.json                            the catalog: one row per document
  documentkb/01a13951-…/metadata.json              source, fingerprint, extractor, "untrusted"
  documentkb/01a13951-…/content.md                 the extracted text agents read
  documentkb/01a13951-…/source.sha256              detects a changed document at the next sync
java-workspace/aidlc/spaces/default/intents/audit/
  <machine>-<id>.md                              DOCUMENT_INDEXED: which document, its digest, when

knowledge/documents/Reviewer-Queue-API-Spec.mdthe spec · real file

# Reviewer Queue API: Product Specification

| | |
|---|---|
| Document | Reviewer Queue API: Product Specification |
| Version | 1.3 (approved) |
| Owners | Ravi Menon (Utilization Management), Meena Iyer (Engineering) |
| Library | Prior Auth Platform > Product > Specifications |
| Last modified | 12 Oct 2026 |

*Converted from Reviewer-Queue-API-Spec.docx with markitdown for AI-DLC; the Word file in SharePoint is the original.*

## 1. Purpose

The reviewer screen shows the prior-authorization requests that still need a decision. It reads one endpoint, `GET /requests/pending`, from priorauth-api. This document fixes what that endpoint returns and how callers narrow it. It does not cover the screen's layout, the nightly report, or how requests are stored.

## 2. Response

A JSON array, oldest request first. Every row carries `id`, `tenantId`, `service`, `status`, `receivedAt`, and, since version 1.1, `ageBusinessDays`, `overLimit` and `ageLabel`. Fields are never removed or renamed; new fields are added only at the end.

## 3. Narrowing the list

Callers narrow the list with query parameters. Parameters combine with AND. A parameter that is absent does not filter.

| Parameter | Values | Effect |
|---|---|---|
| `asOf` | ISO date, `YYYY-MM-DD` | The date the age is computed for. Default: today. |
| `tenant` | a tenant id, e.g. `TX-01` | Only that tenant's requests. |
| `status` | `PENDED`, `IN_REVIEW` | Only requests with that status. |
| `overLimit` | `true`, `false` | Only requests whose over-limit flag has that value, for the same `asOf`. |

## 4. Errors

A request the API cannot answer correctly gets `400 Bad Request` with a JSON body `{ "error": "<message>" }`. The message names the parameter and, where there is a fixed list, the allowed values.

- An `asOf` that is not a date, or is before a request's received date.
- A `status` outside the list in section 3.
- A `tenant` that is not configured in the platform. A mistyped tenant must not look like an empty queue: reviewers would conclude their work is done.

## 5. Non-functional requirements

- No new runtime dependencies for filtering; the list is small (hundreds of rows) and is filtered in memory.
- Response time for the pending list stays under 500 ms at the 95th percentile, as today.
- The response shape stays backward compatible (section 2): the screen's current release must keep working unchanged.

## 6. Glossary

| Term | Meaning |
|---|---|
| Tenant | A health plan the platform serves, identified by an id such as `TX-01`. |
| Pending | A request in status `PENDED` (waiting on the provider) or `IN_REVIEW` (waiting on a reviewer). |
| Over the limit | Older than the tenant's limit in business days (default 5), as defined in requirement FR2 of intent 261013-request-age-api. |

knowledge/documentkb/01a13951-…/metadata.jsonreal file, as committed

mkdir aidlc\spaces\default\knowledge\documents -Force | Out-Null
Copy-Item docs-in\sharepoint\Reviewer-Queue-API-Spec.md aidlc\spaces\default\knowledge\documents\
aidlc engine knowledge onboard

How Kiran onboarded it, and how you add the next document (Windows; on macOS mkdir -p and cp). Then commit aidlc/.

Word files2.11 has no built-in extractor for .docx: it would be catalogued as unsupported. Convert first, e.g. markitdown Spec.docx -o Spec.md, or onboard a PDF (up to 50 pages are extracted).

Copy firstReal 2.11.0 behaviour: onboard docs-in/x.md answers "docs-in/x.md is outside documents. Copy it under documents/ first, then re-run." The docs say it copies for you; the tool doesn't.

Changed specOverwrite the file in documents/ and run aidlc engine knowledge sync. To remove one: delete the file, then sync. There is no remove verb.

already done · check it

The input rules, already in the team's CLAUDE.md

Claude Code reads CLAUDE.md at every start. Kiran added six lines that tell every stage where stories and specs come from, how to cite them, and what to do when they disagree.

Kiran · 09:25

You type PowerShellTerminal (macOS)

Get-Content CLAUDE.md -Tail 6

tail -6 CLAUDE.md

You see real file

## Inputs from Rally and SharePoint
Features come from Rally as snapshots in docs-in/rally/ (scripts/export-rally.py); Rally is the source of truth for stories.
Cite the story ID (US5120…) next to every requirement, plan row and test; never invent a story.
Product specs come from SharePoint, converted to Markdown and onboarded under aidlc/spaces/default/knowledge/.
When a spec and a story disagree, ask at the gate; never pick one silently.
Refresh both snapshots before /aidlc, and commit them with the record.

Why the team's file, not AI-DLC's memory. aidlc/spaces/default/memory/ holds rules AI-DLC learns and affirms through its own gates; editing it by hand skips that audit. CLAUDE.md is yours: write house rules there.

The runsteps 5–6 · the same 10 stages, different inputs

Claude Code

Start the run, naming both inputs

Start Claude Code in the workspace (claude) and give the request. Naming the spec's path matters: stages read the documents a request names; nothing in 2.11 reads the whole knowledge base on its own.

Kiran · 09:30

You type in Claude Code

/aidlc express Build what ./docs-in/rally/F1187-reviewer-queue-filters.md describes. The product spec is aidlc/spaces/default/knowledge/documents/Reviewer-Queue-API-Spec.md.

Claude returns expected shape, not a transcript

Setting up an express workflow for this: 7 stages, 7 approval gates; no reviewers, sensors,
learnings ritual, summary confirmation, or plan approval; lead agent only.
Intent created: 261014-reviewer-queue-filters (space: default)
State initialized: express scope, 10 stages, Minimal depth
Project type: Brownfield
First post-init stage: reverse-engineering (INCEPTION)
codekb priorauth-api: STALE (scanned at v1.0.2, the repo is at v1.1.0) → rescan of what changed
…
▸ Reverse Engineering is done. How would you like to proceed?  1. Approve  2. Request Changes  3. Other

Choosing the scope. Express asks no scope question: the word in the command is the decision. It fits here: one repo, three small stories that product already accepted, nothing to design. Start with /aidlc feature … instead when the feature spans repos (Units Generation then splits it into one unit per repo) or when the stories are still being argued about (User Stories then runs too, and you'd skip it if Rally stays the source). The first question you answer is the Reverse Engineering gate, as in the hello-world run; choose Yes if Claude Code asks to change the project's settings first.

Optional: once the intent exists, aidlc engine knowledge associate <id> --intent links the spec to it in the catalog, so a later reader of the record sees which document the run used.

the gates

What each gate checks differently, and the one decision only people can make

The stages are the same 10. What changes is what they read and cite. The useful part: the story and the spec disagree, and Requirements Analysis is where that must surface, not in code review.

Kiran, Ravi, Meena · 09:31 →

Stage	Hello-world run	Expected with a Rally feature and a spec
2.1 Reverse Engineering	Full scan, 9 codekb files	Starts from `codekb/priorauth-api/`, which the engine reports STALE at v1.1.0 (tested), so expect a rescan of what changed: the `aging` package
2.3 Requirements Analysis	FR1…FR3 from one message, after 4 lettered questions and 2 follow-ups	One FR per acceptance criterion, each citing it: `FR1 ← US5120 AC1`. NFRs from spec §5. Open questions: Q-1 unknown tenant, 400 (spec §4) or empty list (US5120)? Q-2 the second tenant NM-02 the story note asks for: which rows?
2.4 User Stories	skipped (express)	skipped (express): the Rally stories are the stories
3.5 Code Generation plan	Each row → an FR	Each row → an FR and its story; one row adds NM-02 rows to `requests.sample.json` (Q-2). `traceability.json` maps FR → US → files → tests. A new intent starts with plan approval off again (express): turn it on with your 2.3 approval, as in hello-world step 11. The plan names its own branch: say "use request-filters" when you approve it, or Claude makes a second one, as it did in the real hello-world test
3.6 Build and Test	Matrix per FR; `cross-unit-traceability.md` PASS	The same matrix, now also readable per story: every AC of US5120–US5122 has a passing test
4.1–4.4 Operation	Skipped: no pipeline or deploy config in the workspace	Skipped again, for the same reason, unless the team adds its pipeline config or a deploy runbook to the workspace first

You type in Claude Code, at the 2.3 gate (Request Changes)

2  Q-1: an unknown tenant returns 400, as the spec says: a mistyped tenant must not look like an empty queue. Rally US5120 AC3 is updated to match after the run. Q-2: add two pending NM-02 requests to the sample export. (Ravi, Meena)

Claude returns expected shape, not a transcript

Recorded. requirements.md updated: FR1.3 unknown tenant → 400 (spec §4; overrides US5120 AC3, to be updated in Rally)
  · NM-02 sample rows added to the plan · answers written into requirements-analysis-questions.md with names

The decision: story or spec?

Neither file is wrong on its own; they were written by different people at different times. The gate makes a named person choose, and the audit shard keeps who and why. The losing source gets fixed afterwards (step 8), so Rally and the record agree again.

Answered by Ravi Menon and Meena Iyer

In plain words. Two order slips say different things about the same dish. The cook doesn't guess: they ask the table, write the answer on the ticket, and the waiter corrects the tablet.

Aftersteps 7–9 · the pull request, close the loop, then connect

expected · yours and the tool's

From the plan to the pull request: one branch, one PR

AI-DLC has no pull-request stage in any scope; the PR comes from the team's CLAUDE.md (one unit = one branch = one PR), as PR #58 did in the hello-world run. Express has no units, so this run gets one branch, the request-filters you made at step 1, and one PR. Not run: the engine's stops are the hello-world run's, the git and gh lines are its step 14 with this feature's branch and intent.

expected · Kiran, Meena

	What happens	Whose step	Where it is recorded
1	Plan approval. Claude writes the code-generation plan, each row citing an FR and its story, and stops (if you turned plan approval on at 2.3). Say “use request-filters” here, or the plan names a branch of its own.	the engine stops; Meena answers	`construction/code-generation/code-generation-plan.md`, the audit log
2	Code and tests on `request-filters`, then `scripts/verify`, never an ad hoc `mvn`.	Claude, because `CLAUDE.md` says so	`code-summary.md`; `traceability.json` maps FR → US → files → tests
3	Commit. The code on `request-filters`, the record on the workspace's branch (“commit it after every gate”). Claude Code asks before each `git commit`.	Claude, under the team's rule	both repos' history
4	The 3.5 and 3.6 gates. No unit checkpoint and no verification-command question: express has zero units. The Operation stages skip themselves (step 6).	the engine; Meena answers	`aidlc-state.md`, the audit log
5	Push and open the PR, with the code summary as its description and the Rally IDs in its title, so a search in either tool finds the other.	Kiran	GitHub
6	Review and squash-merge. AI-DLC's own default in `memory/org.md` is trunk-based with squash-merge. Then step 8: write back to Rally.	Meena	GitHub; `main`

You type in Claude Code, two ! lines

! git -C priorauth-api push -u origin request-filters
! gh pr create --repo acme-health/priorauth-api --base main --head request-filters --title "Reviewer queue filters (F1187: US5120-US5122)" --body-file aidlc/spaces/default/intents/261014-reviewer-queue-filters/construction/code-generation/code-summary.md

You see expected shape, the story's GitHub

To github.com:acme-health/priorauth-api.git
 * [new branch]      request-filters -> request-filters
Creating pull request for request-filters into main in acme-health/priorauth-api

https://github.com/acme-health/priorauth-api/pull/61

Following along? Skip both lines. acme-health and PR #61 are the story's GitHub: your origin is the public starter, which you cannot push to. git -C priorauth-api log --oneline -3 shows Claude's commit on request-filters, above v1.1.0.

In feature scope it repeats per unit. Run /aidlc feature … instead (step 5) and Units Generation splits the work; each unit then has its own plan approval, branch, a checkpoint where the engine runs scripts/verify itself and asks “Approve this completed <unit>?”, and its own PR. The feature-scope page, step 11 walks through that loop.

In plain words. One dish, one ticket to the pass. The tool tastes it and the chef signs it off; carrying it out, and telling the table it's served, are the house's jobs.

yours, not the tool

Write the result back to Rally

AI-DLC has no tracker stage, just as it has no PR stage. Closing the loop is a team step: move the stories, fix the criterion the gate overruled, and link the PR and the intent so the next person can find the record from Rally.

Kiran · after the merge

You type in Rally's UI

In Rally, after PR merges (by hand today):
  US5120, US5121, US5122   ScheduleState → Completed (the owner accepts them after the demo)
  US5120                   Acceptance criteria: unknown tenant → 400 (the Q-1 decision)
  F1187                    Discussion: "Delivered in priorauth-api 1.2.0, PR #61, intent 261014-reviewer-queue-filters"

You see tested

(nothing for AI-DLC to do. Then commit the workspace with the hello-world step 17 command, unchanged:
 it already picks up docs-in/rally/, docs-in/sharepoint/, scripts/export-rally.py
 and the knowledge/ files, plus the onboarding audit entry)

Later, through Rally's MCP server: the same three updates become requests to Claude, each one approved by you before it runs (step 9). Keep it to these: a write you didn't read first is how a story's history gets lost.

later

Going live: connect Claude Code to Rally and SharePoint

Connections help around the run: looking up a story while answering a gate, refreshing the export, writing back. They don't replace the committed snapshots. None of this was run for the course; it follows each vendor's documentation as of October 2026.

the team, once

java-workspace/.mcp.jsoncommitted · the key stays in an environment variable

java-workspace/.claude/settings.local.jsonper machine · not committed

RallyBroadcom hosts an official MCP server: https://mcp.rallydev.com/mcp (EMEA: mcp-eu). API key as a Bearer header, or OAuth. Since 2 Oct 2026 it serves four generic tools; rally_openapi_invoke_tool can write, so it stays on ask. Make the key under a read-only account if you only read.

SharePointClaude's Microsoft 365 connector reads SharePoint and OneDrive (Word, PDF, Excel, PowerPoint) with the signed-in user's rights, read-only by default; it reaches Claude Code when you log in with a claude.ai account and ANTHROPIC_API_KEY is not set (Claude Code says so: the key takes precedence and connectors are disabled). A tenant admin consents once. Without it: rclone with read-only scopes, then markitdown.

Where settings go.claude/settings.json is regenerated by aidlc config, so permission rules go in .claude/settings.local.json or your user settings. Tested with 2.11.0: re-running aidlc config, and aidlc config project --mcp defaults --yes / none --yes, add or remove only AI-DLC's five servers and keep your rally entry. Claude Code lists it as "Pending approval" until you approve it once in claude.

Risks to plan for. Text from a story or a document is data, not instructions: AI-DLC marks onboarded documents untrusted, and every agent sees every MCP server, so keep write tools on ask. If stories or specs can contain patient data, check that Anthropic, Microsoft and Broadcom are each covered by your BAA/DPA before any of it goes through them. Admin consent in Entra and a Rally API key are owned by your platform team, not by the run.

What is real here, and what is not

Real: the starter branch and everything on it; export-rally.py and its offline output (the .md is generated from the .json, not typed); the onboarding, the documentkb/ files, the list output and the "outside documents" message, all from AI-DLC 2.11.0 on 14 Oct 2026. Tested from a fresh clone of the branch: aidlc config, workspace-sync (clones the code repo), the export check, knowledge list, and the engine's own readers (it reads the hello-world run as complete, the codekb as STALE at v1.1.0, and starts a new intent for F1187 next to it). Not real: the Rally subscription and the SharePoint library (the files stand in for them; the IDs F1187, US5120–US5122 and E212 are invented), and Claude's output at steps 5 and 6 and the pull request at step 7, which are the expected shape: no AI run was performed for this variant. Tested without real accounts: live mode reaches Rally's API and gets the expected 401 for a wrong key; Claude Code parses the .mcp.json entry; aidlc keeps it. Untested: a real Rally key, Rally's MCP tools, and the Microsoft 365 connector.

Sources: AI-DLC docs on knowledge, CLI commands, Inception stages and Claude features; Claude Code MCP; Broadcom Rally MCP and WSAPI keys; Claude's Microsoft 365 connector; markitdown.