Skip to content

Commit d22c9a9

Browse files
izzetizzet
authored
Merge pull request #140 from grc-iit/feat/agent-guides
Enhance: Add Agent Guides
2 parents 49d97ae + 82111b9 commit d22c9a9

6 files changed

Lines changed: 399 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Agent Guide (Root)
2+
3+
Purpose
4+
5+
- This file orients an automated agent (and humans) to make safe, correct edits.
6+
- The site is data-driven: update YAML in `data/` and pages update automatically via custom plugins.
7+
8+
Tech stack
9+
10+
- Framework: Docusaurus 3 (React 18)
11+
- Dev server: `npm install && npm start` (`http://localhost:4720`)
12+
- Build: `npm run build` → output in `build/`
13+
14+
High-level map (go here for the task you want)
15+
16+
- Add or edit a publication: `data/publications/` (see `data/publications/AGENTS.md`)
17+
- Add or edit a member (researcher/engineer/visiting/external): `data/members/` (see `data/members/AGENTS.md`)
18+
- Add or edit a faculty member: `data/faculty/` (see `data/faculty/AGENTS.md`)
19+
- Add or edit a project definition: `data/projects/` (see `data/projects/AGENTS.md`)
20+
- Add a project details page (MDX content): `src/pages/research/projects/` (see `src/pages/research/projects/AGENTS.md`)
21+
22+
How content flows
23+
24+
- Custom plugins under `plugins/` load YAML and expose the data globally:
25+
- Publications → `plugins/publications/`
26+
- Projects → `plugins/projects/`
27+
- Members (and member-pages) → `plugins/members/`
28+
- List pages are MDX under `src/pages/` and use React components that read plugin data.
29+
- Detail pages are auto-generated by plugins:
30+
- Publications: `/publications/{slug}`
31+
- Members (only `type: researcher`): `/members/{slug}`
32+
33+
Quick rules that prevent surprises
34+
35+
- Keep `slug` values unique in YAML. Routes are built from them.
36+
- Publication authors must be short-name strings (e.g., `A. Kougkas`). Member pages match on this form.
37+
- To associate a publication with a project, include the project `name` as a tag in the publication YAML (e.g., `ChronoLog`, `Hermes`, `WisIO`).
38+
- Member photos live in `static/img/members/` and are referenced by filename in YAML.
39+
- Prefer a consistent publication `date` format (e.g., `June, 2025`). Sorting uses `new Date(date)`.
40+
41+
Common entry points
42+
43+
- Publications list: `src/pages/publications.mdx`
44+
- Projects list: `src/pages/research/projects/index.mdx`
45+
- Members directory: `src/pages/members.mdx`
46+
47+
Where to learn details
48+
49+
- See the folder-local `AGENTS.md` for step-by-step, examples, and schema:
50+
- `data/publications/AGENTS.md`
51+
- `data/projects/AGENTS.md`
52+
- `data/members/AGENTS.md`
53+
- `data/faculty/AGENTS.md`
54+
- `src/pages/research/projects/AGENTS.md`
55+
56+
Advanced (usually not required for content edits)
57+
58+
- Type definitions: `src/types.ts`
59+
- Publication table and detail UI: `src/components/publications/`
60+
- Member list/item/detail UI: `src/components/people/`
61+
- Project list/cards: `src/components/projects/`

‎data/faculty/AGENTS.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Agent Guide: Faculty
2+
3+
Goal
4+
5+
- Enable an agent to add or modify faculty profiles. Files here are YAML and rendered on the Members page under Faculty.
6+
7+
What to edit
8+
9+
- Create or modify a `*.yaml` file. Faculty YAML extends `Member` with an `order` field and `type: faculty`.
10+
11+
Fields
12+
13+
- `name`
14+
- `title`
15+
- `type: faculty`
16+
- `slug` (unique)
17+
- `image` (filename in `static/img/members/`)
18+
- `links` (map; keys like `email`, `linkedin`, `scholar`, `website`)
19+
- `bio` (string)
20+
- `order` (number; controls display order)
21+
22+
Routing
23+
24+
- Faculty currently do not get auto-generated detail pages. They appear on `/members` under the Faculty section.
25+
26+
Example
27+
28+
```yaml
29+
name: Dr. Anthony Kougkas
30+
title: Research Associate Professor
31+
type: faculty
32+
slug: anthony-kougkas
33+
image: kougkas.jpg
34+
links:
35+
email: akougkas@illinoistech.edu
36+
linkedin: https://www.linkedin.com/in/anthonykougkas/
37+
scholar: https://scholar.google.com/citations?user=hiNO0EEAAAAJ&hl=en
38+
website: https://akougkas.com/
39+
order: 2
40+
bio: >-
41+
Short bio...
42+
```
43+
44+
Preview
45+
46+
- Run from repo root: `npm start`
47+
- Visit `/members`

‎data/members/AGENTS.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Agent Guide: Members
2+
3+
Goal
4+
5+
- Enable an agent to add or modify member profiles. Files here are YAML, consumed by the members plugin.
6+
7+
Member categories
8+
9+
- Researchers, engineers, visiting, external are in this folder.
10+
- Faculty profiles are under `data/faculty/`.
11+
12+
What to edit
13+
14+
- Create or modify a `*.yaml` file with these fields (see `Member` in `src/types.ts`).
15+
16+
Common fields
17+
18+
- `name` (e.g., `Hua Xu`)
19+
- `title` (e.g., `PhD Candidate`)
20+
- `type` (`researcher` | `engineer` | `visiting` | `external`)
21+
- `slug` (used for researcher page routes; must be unique)
22+
- `image` (filename in `static/img/members/`)
23+
- `links` (map of link types to URLs; keys: `website`, `email`, `github`, `linkedin`, `orcid`, `twitter`, `scholar`)
24+
- `researchInterests` (array of strings)
25+
- `bio` (string)
26+
- Optional: `advisor`, `affiliation`
27+
28+
Routing
29+
30+
- Researcher pages are auto-generated at `/members/{slug}` only for entries with `type: researcher`.
31+
- Other types (engineer/visiting/external) appear on the directory page but do not get detail pages.
32+
33+
Publication matching
34+
35+
- Member pages display publications matched by short-name author format `F. Lastname`. Ensure publication YAMLs list the author in that form so they show up.
36+
37+
Images
38+
39+
- Place images in `static/img/members/` and reference by filename in `image:`.
40+
41+
Examples
42+
43+
Researcher with page:
44+
45+
```yaml
46+
name: Hua Xu
47+
title: PhD Candidate
48+
type: researcher
49+
slug: hua-xu
50+
image: xu.jpg
51+
links:
52+
email: hxu40@hawk.illinoistech.edu
53+
researchInterests:
54+
- HPC
55+
- Distributed Storage
56+
bio: >-
57+
Short bio...
58+
advisor: Dr. Xian-He Sun
59+
```
60+
61+
External collaborator (no detail page):
62+
63+
```yaml
64+
name: Jane Doe
65+
title: Collaborator
66+
type: external
67+
slug: jane-doe
68+
image: jane.jpg
69+
links:
70+
website: https://example.com
71+
```
72+
73+
Preview
74+
75+
- Run from repo root: `npm start`
76+
- Visit `/members`

‎data/projects/AGENTS.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Agent Guide: Projects
2+
3+
Goal
4+
5+
- Enable an agent to add or modify project definitions. Projects here are YAML entries exposed globally and rendered via components.
6+
7+
What to edit
8+
9+
- Create or modify a `*.yaml` file representing a project. Fields correspond to `Project` in `src/types.ts`.
10+
11+
Required/common fields
12+
13+
- `id` (kebab-case string; used to name optional MDX page and cross-references)
14+
- `name` (human name; used in tags for publications association)
15+
- `title` (string)
16+
- `shortDescription` (string)
17+
- `link` (URL path to the project details page, typically `/research/projects/{id}`)
18+
- `researchStatus` (`ready` | `testing` | `r&d`)
19+
- `status` (`active` | `archived`)
20+
- `type` (`funded` | `student`)
21+
22+
Optional fields
23+
24+
- `isFeatured` (boolean)
25+
- `isOurs` (boolean)
26+
- `sourceLink` (external repo URL)
27+
- `tutorialLink` (docs link)
28+
29+
Rendering
30+
31+
- Projects list page: `src/pages/research/projects/index.mdx` via `ProjectList`.
32+
- Project cards/items: `src/components/projects/`.
33+
- Data is loaded by `plugins/projects/` and available through global data.
34+
35+
Per-project content (MDX)
36+
37+
- If you want a detailed content page: create `src/pages/research/projects/{id}.mdx` and set `link: /research/projects/{id}` in YAML.
38+
39+
Publication association
40+
41+
- To show related publications in a project widget elsewhere, ensure publication YAMLs include the project `name` in their `tags`.
42+
43+
Examples
44+
45+
```yaml
46+
id: chronolog
47+
name: ChronoLog
48+
title: 'ChronoLog: A High-Performance Storage Infrastructure for Activity and Log Workloads'
49+
shortDescription: >-
50+
One or two sentences about the project.
51+
link: /research/projects/chronolog
52+
isFeatured: true
53+
isOurs: true
54+
researchStatus: testing
55+
sourceLink: https://github.com/grc-iit/chronolog
56+
status: active
57+
tutorialLink: /docs/category/chronolog
58+
type: funded
59+
```
60+
61+
Checklist
62+
63+
- `id` is unique, lower-case, kebab-case
64+
- `link` points to an existing MDX page if you set it to `/research/projects/{id}`
65+
- If you expect publications to associate, confirm their `tags` include this project `name`
66+
67+
Preview
68+
69+
- Run from repo root: `npm start`
70+
- Visit `/research/projects`

‎data/publications/AGENTS.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Agent Guide: Publications
2+
3+
Goal
4+
5+
- Enable an agent to add or modify publications safely. Publications are stored as YAML files here. Pages are generated automatically.
6+
7+
What to edit
8+
9+
- Create a new `*.yaml` file or edit an existing one. Ensure fields match the `Publication` type in `src/types.ts`.
10+
11+
Required fields
12+
13+
- `title` (string)
14+
- `authors` (array of short-name strings, e.g., `A. Kougkas`)
15+
- `venue` (string)
16+
- `type` (one of: `Conference`, `Journal`, `Book`, `Book Chapter`, `Poster`, `Technical Report`, `Thesis`, `WIP`, `Workshop`)
17+
- `date` (string, human-readable; e.g., `June, 2025`) – used for sorting
18+
- `tags` (array of strings)
19+
- `links` (map of string→url; keys like `pdf`, `bibtex`, `code` are common)
20+
- `slug` (string, unique; becomes the URL segment)
21+
22+
Optional fields
23+
24+
- `abstract` (string)
25+
- `doi` (string)
26+
- `month` (number)
27+
- `year` (number)
28+
29+
Routing and rendering
30+
31+
- Detail page path: `/publications/{slug}`
32+
- List page: `src/pages/publications.mdx`
33+
- Data is loaded by `plugins/publications/` and consumed by components in `src/components/publications/`.
34+
35+
Project associations
36+
37+
- To show a publication in a project’s publications widget, add the project `name` (not id) to `tags`. Example: `ChronoLog`, `Hermes`, `WisIO`.
38+
39+
Author matching for member pages
40+
41+
- Member pages match authors using short-name format `F. Lastname`. Ensure your `authors` follow this convention so the publication appears on relevant member pages.
42+
43+
Examples
44+
45+
Minimal valid entry:
46+
47+
```yaml
48+
title: Example Title
49+
authors:
50+
- A. Kougkas
51+
- X.-H. Sun
52+
venue: ExampleConf 2025
53+
type: Conference
54+
date: June, 2025
55+
tags:
56+
- HPC
57+
- Hermes
58+
links:
59+
pdf: https://example.com/paper.pdf
60+
slug: kougkas-2025-example-1234
61+
```
62+
63+
With optional fields:
64+
65+
```yaml
66+
title: WisIO: Automated I/O Bottleneck Detection with Multi-Perspective Views for HPC Workflows
67+
authors:
68+
- I. Yildirim
69+
- H. Devarajan
70+
- A. Kougkas
71+
- X.-H. Sun
72+
- K. Mohror
73+
venue: ICS 2025
74+
type: Conference
75+
date: June, 2025
76+
month: 6
77+
year: 2025
78+
tags:
79+
- HPC
80+
- Workflows
81+
- WisIO
82+
links:
83+
pdf: https://example.com/wisio.pdf
84+
bibtex: https://example.com/wisio.bib
85+
slug: yildirim-2025-wisio-45f7
86+
abstract: >-
87+
Short abstract here...
88+
doi: 10.1145/xxxx.yyyy
89+
```
90+
91+
Validation checklist
92+
93+
- `slug` is unique in this folder
94+
- `type` is one of the accepted values
95+
- `authors` are in short-name format
96+
- `date` parses reasonably; keep a consistent `Month, Year` style
97+
- If you expect the publication under a project, include the project `name` in `tags`
98+
99+
Preview
100+
101+
- Run the dev server from the repo root: `npm start`
102+
- Visit `/publications` or `/publications/{slug}`

0 commit comments

Comments
 (0)