Context

# Context

## Overview

This repo contains a project knowledgebase. The user uses an LLM to interact with it by asking questions and providing context. This rule is a foundation rule, other rules will override it.

## Important rules which always apply

1. Completely ignore the /src directory if it's present.

## Glossary of terms

Maintain a GLOSSARY.md file make sure you speak the same language as the user. Always load this to ensure you are speaking the same language as the user. New or ambiguous terms should go into an Unknown section at the bottom of the file. The user can provide this context at a later time.

## Directory structure

All knowledge is well organized into the following directory structure:

### Project storage

`/projects` - project knowledge is organized underneath the projects folder.
`/projects/:project_name/` - each project gets its own subfolder.
`/projects/:project_name/README.md` - an overview and index file for this project.
`/projects/:project_name/work/:work_item.md` - a file containing details about large pieces of work.
`/projects/:project_name/progress/` - folder containing progress updates.
`/projects/:project_name/progress/:year/:month.md` - monthly update files.
`/projects/_unknown_project/` - contains project information where the project name is not known.

### People files

`/people` - knowledge about people is organized underneath the people folder.
`/people/:team/` - each person goes into a team.
`/people/:team/:person_name.md` - a file for each person. It tracks interest, ideas, work and successes.
`/people/_unknown_team/` - contains people where team information is not known.

* If the folder doesn't exist, create it unless the user has specified otherwise.

### Questions

`/questions` - saved queries or prompts that generate predictable output.
`/questions/:question_name.md` - a question file describing a prompt and its expected output.

## README.md files

All folders have a README.md file. README.md files provide a summary and index of the folder. They link to every file or subfolder inside it, allowing the user to traverse the knowledgebase.

Whenever a change is made to a file, the agent should consider whether an update to the README.md is also required.

## File formats

### `/projects/:project_name/README.md` - Project file

A project file contains an overview of the project, and links to all relevant work.

### `/projects/:project_name/work/:work_item` - Task file

A task file contains details about large tasks. 

> For smaller tasks, a bullet point in a list is usually enough.b

### `/projects/:project_name/progress/:year/:month.md` - Progress file

Progress is broken down into months. Each entry is added under a heading with the date it was recorded (e.g. `## 3 December 2025`). Newer entries appear at the top of the file. Where possible, include the GitHub username of the person who gave the update at the end of the line (e.g. `* Fixed a bug @username`).

```
# Dashboard Redesign December updates

## 3 December 2025

### Performance

* Reduced initial load time by 40% through lazy loading @sarahchen
* Implemented caching layer for API responses @sarahchen
* Optimized bundle size by removing unused dependencies @marcusjohnson

### Bug fixes

* Fixed timezone display issue in date pickers @emilywong
* Resolved memory leak in real-time data polling @sarahchen
* Corrected pagination offset calculation @emilywong

## 1 December 2025

### New features

* Added dark mode toggle to user preferences @marcusjohnson
* Implemented export to CSV functionality @emilywong
* Created new notification settings panel @sarahchen

### Documentation

* Updated API reference for v2 endpoints @marcusjohnson
* Added troubleshooting guide for common issues
* Improved onboarding walkthrough for new users @emilywong

```

### `/people/:team/:person_name.md` - Person profile file

```
# Sarah Chen

* Team: Platform
* Role: Senior Software Engineer
* GitHub: @sarahwillgetyou

## Current focus

* [API Gateway migration](/projects/api-gateway/ideas.md)
* Performance testing for the new caching layer
* Mentoring two junior developers

## Up next

* Design doc for event-driven architecture
* Evaluate new observability tooling
* Tech talk on distributed tracing

## Ideas

* 2024-12-10 - Could we use feature flags to gradually roll out the new auth flow?
* 2024-11-28 - Might be worth exploring GraphQL federation for the microservices
* 2024-11-15 - Team retrospective format could include async pre-work

## Wins

* 2024-12-15 - Led successful migration of 50+ services to new API gateway
* 2024-11-20 - Reduced P99 latency by 60% on critical payment endpoint
* 2024-10-05 - Promoted to Senior Engineer
* 2024-09-12 - Open source contribution merged into Kubernetes

## Interests

* 2024-12-01 - Rust and systems programming
* 2024-10-15 - Distributed systems and consensus algorithms
* 2024-08-20 - Technical writing and documentation
```

* `Team` - the person's team - when changed, the path should also be updated and vice versa.
* `Role` - the person's role.
* `Current focus` - a list of things the user is currently working on. If possible, these will link (via markdown links) to files within the projects directory.
* `Up next` - a list of things the user will look at in the near future.
* `Ideas` - A list of ideas the user is thinking about.
* `Wins` - A list of this person's wins that are worth celebrating.
* `Interests` - a list of things this user is interested in. When the LLM notices this person's name associated with a topic, this list may be updated.

### `/questions/:question_name.md` - Question file

A question file contains a saved prompt that generates predictable, repeatable output from the knowledgebase.

```
# Team Overview

Generate a concise overview of each person in the team and what they're currently working on.

## Prompt

Read all person files from the /people folder. For each person, output:

- Their name and role
- Their current focus items (from the "Current focus" section only)

Keep it brief. Do not include historical information, wins, ideas, or interests.
Format as a simple list grouped by team.

## Example output

## Platform

**Sarah Chen** (Senior Software Engineer)
- API Gateway migration
- Performance testing for the new caching layer
```

* The heading describes what the question generates.
* `Prompt` - the prompt for the LLM to execute.
* `Example output` - an example of what the output should look like.

## Scripts

The LLM may run the following scripts:

* `.context/scripts/print_datetime.sh` - Print the current date and time.
* `.context/scripts/random_dir.sh` - Selects a random directory from the root.
* `.context/scripts/random_project.sh` - Selects a random project.
* `.context/scripts/random_person.sh` - Selects a random person. 
* `.context/scripts/print_dir_structure.sh` - prints the current directory structure which the LLM should respect.