Skip to content

docs: add curated AI context and maintenance guidance #18

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
codeforester wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add curated AI context and maintenance guidance #18

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions .ai-context/ARCHITECTURE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Architecture

The durable configuration is `workspace.yaml`: schema version, workspace name,
and repository entries with URL, default branch, and required/optional status.
`base_manifest.yaml` independently identifies this repository as a Base-managed
project and declares its validation command.

Base implements parsing, clone/update operations, status, checks, and diagnostics.
This repository supplies their input. No runtime service or package import is
needed to read the inventory. Standard contributor, issue, and CI files provide
repository governance rather than another workspace engine.

`tests/validate.sh` checks the repository baseline and the exact seven-repository
contract, including canonical URLs, main branches, required flags, and exclusions.
A deliberate inventory change therefore needs a matching test change and review;
adding a documentation pack does not change workspace membership.

Sources: [workspace.yaml](../workspace.yaml), [project manifest](../base_manifest.yaml),
[validation driver](../tests/validate.sh), and
[contribution guide](../CONTRIBUTING.md).
11 changes: 11 additions & 0 deletions .ai-context/INDEX.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# base-workspace AI context index

Read in this order:

1. [Project](PROJECT.md): purpose, audience, scope, and boundaries.

@codeforester codeforester Oct 21, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

INDEX.md doesn't self-reference, so it exports LAST despite being the stated entry point. .ai-context/README.md (line 5-6) says "Start with INDEX.md," and the exporter (base_export_context/engine.py: ordered_context_files/index_references) builds Markdown-export order by parsing the markdown links/code-spans found inside INDEX.md, in order of appearance, then appends any unreferenced files alphabetically. Since this INDEX.md never links to itself, it isn't in that reference list, so it gets appended at the end.\n\nI confirmed this by actually running basectl export-context --list-files against this PR's worktree:\n\n.ai-context/PROJECT.md\n.ai-context/ARCHITECTURE.md\n.ai-context/WORKFLOWS.md\n.ai-context/README.md\n.ai-context/INDEX.md\n\nINDEX.md — the page meant to be read first — is last in the actual exported/printed bundle a reader or AI tool consumes via basectl export-context --print. (Note: this same pattern already exists in base-bash-libs/.ai-context/INDEX.md, so it's not unique to this PR, but it's being newly copied here too.)

2. [Architecture](ARCHITECTURE.md): components, contracts, and source map.
3. [Workflows](WORKFLOWS.md): setup, validation, and contribution practices.
4. [Maintenance](README.md): sources, update rules, and export behavior.

The pack is curated orientation. Canonical repository sources linked from each
page take precedence when exact implementation or policy details matter.
19 changes: 19 additions & 0 deletions .ai-context/PROJECT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Base workspace inventory

`base-workspace` maintains the version-controlled inventory for a canonical Base
workspace. It is a small manifest repository, not a runtime, application, or
replacement for the Base CLI.

`workspace.yaml` declares four required repositories: base, base-bash-libs,
base-cli, and base-workspace. It also declares three optional reference consumers:
base-demo, base-cli-demo, and base-bash-libs-demo. Optional demos support validation
and development without becoming prerequisites for a normal Base checkout.

Other repositories can coexist under the same local workspace root while
remaining outside this inventory. Directory discovery by `basectl projects list`
and manifest-selected workspace operations answer different questions. Use a
separate manifest to manage a different group; do not silently expand this
canonical inventory to every checkout on one person's machine.

Sources: [README](../README.md), [workspace manifest](../workspace.yaml), and
[manifest validation](../tests/validate.sh).
27 changes: 27 additions & 0 deletions .ai-context/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# AI context for base-workspace

This directory is the repository's curated orientation for AI-assisted work and
portable export. It summarizes verified repository behavior; it is not generated
runtime evidence or an authoritative release/status registry. Start with
[INDEX.md](INDEX.md).

Keep purpose, architecture, commands, and workflows aligned with code and
canonical documentation. Update the affected pages in the same meaningful PR;
for typo-only or internal changes with no contract impact, record no context
impact in the PR. Resolve disagreements by correcting this pack from its sources.
Do not copy credentials, local databases, private machine paths, personal records,
or transient logs into it. Link to evidence rather than copying runtime data.

From this checkout, with Base available:

```bash
basectl export-context --list-files
basectl export-context --print
```

Markdown exports combine Markdown files in INDEX order, then append unlisted
files deterministically. Links outside this directory are source references;
the exporter does not inline their targets. Keep core explanations self-contained.
Use real regular files, not symlinks. Store generated bundles outside the project
and keep generation timestamps out of source pages so unchanged exports remain
byte-identical. This pack is picked up automatically by workspace export jobs.

@codeforester codeforester Oct 21, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unverified claim: no "workspace export job" exists anywhere in this org. I searched this repo's CI (.github/workflows/issue-branch-policy.yml, project-intake.yml, and tests.yml, which only runs ./tests/validate.sh) and the sibling base, base-cli, and base-bash-libs repos for any automated job that reads/exports .ai-context/ and found none — the only way this pack gets exported is a human (or agent) manually running basectl export-context. (The identical sentence already appears in base-bash-libs/.ai-context/README.md, so this looks like copied boilerplate rather than something verified for this repo.) If there's no such job, this line overstates what happens automatically and could lead a reader to assume the pack is kept fresh/consumed without anyone acting on it. Worth confirming the intended meaning and either pointing to the actual mechanism or dropping the sentence.

27 changes: 27 additions & 0 deletions .ai-context/WORKFLOWS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# Workflows

With Base available, run the manifest-oriented read/plan commands from this
repository. Specify the intended workspace root when it differs from Base's

@codeforester codeforester Oct 21, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instruction conflates --manifest with workspace root. This paragraph says to "specify the intended workspace root when it differs from Base's configured workspace," but every example below only passes --manifest workspace.yaml — never --workspace <path>. These are two distinct flags (confirmed via basectl workspace status --help): --manifest selects which YAML inventory file to read; --workspace <path> selects which directory on disk gets scanned for the repo checkouts (defaults to workspace.root/BASE_HOME's parent). I verified empirically: running basectl workspace status --manifest workspace.yaml from a worktree in a completely different directory still reported "workspace": "/Users/rameshhp/work" (Base's configured default), not the directory it was run from. So a contributor whose checkout root actually differs from Base's configured workspace, following this guidance literally, will get status/check/doctor/clone output scoped to the wrong directory while believing --manifest fixed that — they'd need --workspace <path> as well (or instead).\n\nSuggest either dropping the "workspace root" sentence, or adding --workspace <path> to the examples and explaining the two flags separately.

configured workspace:

```bash
basectl workspace status --manifest workspace.yaml
basectl workspace check --manifest workspace.yaml
basectl workspace doctor --manifest workspace.yaml
basectl workspace clone --manifest workspace.yaml --dry-run
./tests/validate.sh
git diff --check
```

A real clone creates local repositories. Optional demos require
`--include-optional`; their presence is not required for the normal workspace.
Review a plan before changing repositories, and preserve existing local work.
Use a separate inventory for unrelated personal or integration repositories.

Make inventory or documentation changes through an issue-backed canonical
branch and a dedicated worktree. Link the PR, record validation, and update
README/tests together when membership changes. Context-only updates do not
change VERSION, the workspace's repository set, or any sibling checkout.

Sources: [README commands](../README.md), [contribution guide](../CONTRIBUTING.md),
[workspace contract](../workspace.yaml), and [validation](../tests/validate.sh).
14 changes: 14 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,3 +43,17 @@ basectl check base-workspace
basectl doctor base-workspace
basectl test base-workspace
```

## AI Context Maintenance

Start AI-assisted orientation with [.ai-context/INDEX.md](.ai-context/INDEX.md).
Maintain these curated summaries alongside meaningful changes to product scope,

@codeforester codeforester Oct 21, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

New .ai-context maintenance obligation has no CI enforcement. CONTRIBUTING.md now asks contributors to "maintain these curated summaries alongside meaningful changes" and "state context impact in the PR," but tests/validate.sh's required_files array (which .github/workflows/tests.yml runs on every push/PR) was not extended to include anything under .ai-context/. I confirmed this directly: deleting the entire .ai-context/ directory from the PR worktree and re-running ./tests/validate.sh still printed Repository baseline is present. and exited 0.\n\nSo a future PR can delete, rename, or let the pack go stale with CI staying green — nothing catches it. Consider adding the 5 .ai-context/*.md files to required_files (or a dedicated check) so the pack gets the same CI protection as README.md, CHANGELOG.md, etc.

architecture, commands, or contributor workflows. Canonical docs and code remain
the source of truth; update the pack when they disagree. State context impact in

@codeforester codeforester Oct 21, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR template checklist wasn't updated to match this new rule. This line asks contributors to "state context impact in the PR," the same way the repo already requires for docs and CHANGELOG — but .github/pull_request_template.md's Checklist has - [ ] Documentation is updated when behavior or user-facing commands change. and - [ ] CHANGELOG is updated for notable user-visible or release-worthy changes. with no analogous .ai-context item. Since the template is what a contributor actually fills in when opening a PR, this new convention has no prompt anywhere in the authoring flow (and this PR itself doesn't visibly state a context-impact line in its own description, which is a live example of the gap). Suggest adding a checklist item, e.g. "AI context pack (.ai-context/) is updated or its non-update is explained."

the PR, including a reason when no update is needed. Typo-only and internal changes
without behavioral or architectural impact usually need no context update.

Validate changes with `basectl export-context --list-files` and
`basectl export-context --print` from the checkout, plus `git diff --check`.
Keep the pack self-contained enough for offline reading, free of secrets and
private runtime data, and independent of generated timestamps or export bundles.
Loading