Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
26 changes: 26 additions & 0 deletions .claude/agents/environment-agent.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
---
name: environment-agent
description: Analyze the vacuum robot grid and valid actions
tools: Read, Grep, Glob
model: sonnet
skills:
- grid-validation
---

Analyze the following 4x4 vacuum robot grid:

S 0 0 0
0 X 0 0
0 0 0 0
0 -1 0 10

Tasks:
1. Identify all valid states.
2. Identify possible robot actions.
3. Determine obstacle and boundary constraints.
4. Propose a state representation.
5. Report any missing requirements.

Work independently.
Do not implement Q-learning.
Do not modify repository files.
26 changes: 26 additions & 0 deletions .claude/agents/reward-agent.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
---
name: reward-agent
description: Investigate unknown reward behavior
tools: Read, Grep, Glob
model: sonnet
---

Investigate the vacuum robot reward function.

Grid:
S 0 0 0
0 X 0 0
0 0 0 0
0 -1 0 10

Tasks:
1. Identify known reward values.
2. Determine what reward information is missing.
3. Explain how rewards could be observed
through interaction with the environment.
4. Identify possible terminal conditions.
5. Report assumptions separately from facts.

Work independently.
Do not implement Q-learning.
Do not modify repository files.
25 changes: 25 additions & 0 deletions .claude/agents/transition-agent.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
---
name: transition-agent
description: Investigates transition and reward behavior
tools: Read, Grep, Glob, Bash
model: sonnet
skills:
- transition-testing
- reward-design
---

You are investigating a reinforcement
learning vacuum robot environment.

Read context/vacuum-environment.md.

Your responsibilities:
1. Identify known transition rules.
2. Identify known reward values.
3. Examine relevant repository code.
4. Report missing T and R definitions.
5. Suggest questions for the instructor.

Do not edit files.
Do not implement Q-learning.
Do not invent missing requirements.
41 changes: 41 additions & 0 deletions .claude/agents/validation-agent.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
---
name: validation-agent
description: Validate the vacuum robot environment implementation against the known requirements
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are validating a reinforcement
learning vacuum robot environment.

Read context/vacuum-environment.md.

Your responsibilities:
1. Check the implementation against the
known facts:
- Grid size: 4x4
- Start: (0,0)
- Obstacle: (1,1)
- Penalty location: (3,1)
- Goal location: (3,3)
2. Verify the robot cannot enter the
obstacle or leave the grid.
3. Run any existing tests or scripts
and report the results faithfully.
4. Identify behavior that relies on
assumptions about the unknown items
(transition model T, complete reward
function R, movement probabilities,
invalid action behavior, terminal-state
rules).
5. Report confirmed facts separately
from assumptions.

Use Bash only to run existing code or
tests. Do not use it to create, edit,
or delete files.

Work independently.
Do not edit files.
Do not implement Q-learning.
Do not invent missing requirements.
15 changes: 15 additions & 0 deletions .claude/settings.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "bash \"$CLAUDE_PROJECT_DIR/scripts/context-switcher.sh\"",
"timeout": 10
}
]
}
]
}
}
11 changes: 11 additions & 0 deletions .claude/skills/grid-validation/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
name: grid-validation
description: Validate the vacuum robot grid definition. Use when creating or editing the environment, grid, or terminal states.
---

# Grid Validation Procedure
1. Confirm the grid is 4x4 with start at (0,0).
2. Confirm exactly one wall at (1,1), one -1 terminal at (3,1), one +10 terminal at (3,3).
3. Confirm terminal states have no outgoing transitions.
4. Confirm a path exists from start to the goal.
5. Report pass/fail for each check.
24 changes: 24 additions & 0 deletions .claude/skills/reward-design/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
---
name: reward-design
description: Choose, check, and justify the reward and hyperparameter values (living reward, discount factor, learning rate, epsilon) for the vacuum robot. Use when setting or changing reward values or Q-learning hyperparameters.
---

# Reward and Hyperparameter Design Procedure

## Current values (source of truth: context/vacuum-environment.md)
- Living reward: -0.04 per step
- Discount (gamma): 0.9
- Learning rate (alpha): 0.1
- Epsilon: 0.1

## Steps
1. Read context/vacuum-environment.md and confirm the values above match it. If they differ, report the mismatch and do not silently pick one.
2. Check each value against these rules:
- Living reward must be small and negative compared to the terminal rewards (+10 goal, -1 pit), so the robot prefers short paths but still reaches the goal.
- Gamma must be strictly between 0 and 1. Too low and the +10 will not propagate back to the start.
- Alpha must be between 0 and 1. Smaller is more stable, larger learns faster but is noisier.
- Epsilon must be between 0 and 1. Note any plan to decay it.
3. Write a 1-2 sentence justification for each value.
4. Remember the robot does NOT know R or T. The reward function belongs to the environment. The agent only sees rewards returned by step(). Never let agent code read the reward table directly.
5. If a value is changed, record the old value, new value, and reason in the Decision Log in context/vacuum-environment.md.
6. Report a short summary table: parameter, value, justification, pass/fail.
20 changes: 20 additions & 0 deletions .claude/skills/transition-testing/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
---
name: transition-testing
description: Test the vacuum robot environment's movement and transition behavior. Use when writing, running, or reviewing tests for step(), actions, wall bumps, or terminal states.
---

# Transition Testing Procedure

Tests go in tests/. Run them with: python -m pytest tests/ (or python -m unittest if pytest is not installed).

## Cases to cover
1. **Normal moves:** from (0,0), moving right goes to (0,1) and moving down goes to (1,0).
2. **Edge bumps:** from (0,0), moving up or left leaves the state at (0,0).
3. **Wall bump:** the wall at (1,1) cannot be entered. From (1,0), moving right stays at (1,0). From (0,1), moving down stays at (0,1).
4. **Terminal states:** entering (3,3) returns reward +10 and done=True. Entering (3,1) returns reward -1 and done=True.
5. **Living reward:** a normal non-terminal move returns the living reward (-0.04).
6. **Interface:** step(state, action) returns (next_state, reward, done) and nothing else leaks out, such as the full reward table.
7. **Determinism:** unless the assignment specifies noisy movement, the same state and action must always give the same result.

## Report
List each case with pass/fail. For any failure, show the state, action, expected result, and actual result.
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ __pycache__/
*.py[cod]
*.pyo
*.pyd
*.pyc
*pytest_cache

# Virtual environments
.venv/
Expand Down
Binary file added Catrina-Project-2.mp4
Binary file not shown.
32 changes: 32 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,35 @@
# Project 2: Agent Skills Component for mini-coding-agent
Group 11: Catrina Coons, Yulisa Medrano


----
# Handoff to Yulisa for 2nd Part of the Project:

I've finished the first half of the SDLC: intent, spec, plan, plus a README draft, and my video. They're in intent/agent-skills/ and README.md is drafted. Everything from here on is yours: implementation into mini-coding-agent.py, skills from the Lab 5 and testing it, finish the README, and your half of the video. Treat spec.md as the contract and plan.md as your guide, it will walk you through the implementation. The requirement numbers (R1–R21) are meant to show up in your test names and commit messages. You can then import the skills from Lab 5, just be sure to change the file path and add the keywords. Tune the agent with a few test prompts to see if it triggers the skills from keywords correctly, then have it build the vacuum robot environment just like we made Claude Code do for Lab 5.

If you disagree with a design decision, go ahead and change it. Just update spec.md/plan.md in the same commit. Lmk if you have any questions!

----

mini-coding-agent already has five of the six coding-agent components from class. This
fork adds the missing one: agent skills. The agent finds skill folders such as skills/
reward-design/SKILL.md, checks each request against them using keyword similarity, loads
the best match into its prompt, and can also load a skill on its own during a task. Every
prompt, similarity check and executed skill is logged. We demonstrate it by having the
agent build and train a Q-learning vacuum robot (the Lab).

## SDLC documents

intent.md - The problem, the desired outcome, constraints, open questions
spec.md - Numbered requirements R1–R21, the design, areas of concern
plan.md - Files that change, order of work (citing R#), risks, proof

## How the skills componenet works

[TODO]

### Requirements are unchanged from original Mini-Coding_Agent directions

 
# Mini-Coding-Agent

Expand Down
Binary file added YulisaVideoProject2.mp4
Binary file not shown.
61 changes: 61 additions & 0 deletions intent/agent-skills/intent.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
# Intent: mini-coding-agent can find and follow agent skills

Author: Catrina Coons. Status: draft (2026-11-16).

## Problem <!-- what can't be done today -->

mini-coding-agent has five of the six components covered in class (repo context, prompt shape, tools and permissions, context reduction, memory, delegation), and now it has the skills component. When we solved the vacuum-robot Lab, we wrote skills (grid-validation, reward-design, transition-testing skills that are in .claude/skills/ folder) that capture the rules the work must follow. mini-coding-agent can use them. It does know a .claude/skills/ folder exists. It can tell when a request needs one of these skills based on the user prompt, and it can load a skill's instructions into what the model sees. So every prompt has to restate those rules by hand, or they get ignored.

We can record whether a skill was considered on used. So we can show, debug, or why the agent did or did not follow a skill.

## Proposed outcome <!-- what better looks like -->

The agent finds skill folders such as .claude/skills/grid-validation/SKILL.md, .claude/skills/reward-design/SKILL.md, .claude/skills/transition-testing/SKILL.md in the workspace.

When a user prompt matches a skill's description closely enough, the agent puts that skill's instructions into the prompt and follows them. Nobody has to name the skill.

If the agent realizes partway through a task that it needs a skill, it can load that skill on its own.

Every decision is logged: the prompt, the similarity check (each skill's score), and which skill ran.

To prove it works, the agent uses our Lab skills to build the vacuum-robot environment and train a Q-learning agent on it.

### Affected users and systems

Anyone running mini-coding-agent who wants repeatable, rule-following behavior on a recurring kind of task.

MiniAgent.ask() / prompt() (where the prompt is assembled), build_tools() (a new tool), and .mini-coding-agent/ (where the new log goes).

The default local model (qwen3.5:4b) is small. Whatever we build has to work with a model that has a short context and weak reasoning.

## Constraints <!-- non-negotiables -->

Python standard library only. No new pip dependencies, and no embedding model.

The similarity check uses keyword matching, the approach used in class.

"ask" stays the default approval policy. Skills never bypass approval.

Existing behavior and existing tests keep working when there is no skills/ folder.

Skills use the format from class: YAML frontmatter (name, description), then numbered, checkable rules, ending with a check that leaves evidence.

### Out of scope

Embedding or LLM-based semantic matching.

Hooks or CI checks that enforce skill rules. Skills stay advisory.

Downloading or sharing skills between repositories.

## Open questions <!-- carried into spec.md -->

What exactly counts as "similar enough"? Which words are compared, how is the score computed, and what is the threshold?

Should more than one skill be able to load for the same prompt?

Where in the prompt does the skill text go so it doesn't break prompt-prefix reuse?

When the model loads a skill mid-task, does that skill stay active for the rest of the request?

Do delegated child agents get skills too?
52 changes: 52 additions & 0 deletions intent/agent-skills/plan.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# Plan: mini-coding-agent can find and follow agent skills

Author: Catrina Coons. Status: draft (2026-11-16). Source: intent/agent-skills/intent.md, intent/agent-skills/spec.md

## Files that change

mini_coding_agent.py: new SkillLibrary class; changes to MiniAgent.__init__, build_tools() (load_skill), build_prefix() (skill list), prompt() (active skills section), ask() (prompt-time check, reset active set) and tool_delegate() (child shares the library); build_agent() / build_arg_parser() (new flags); main() (/skills command); HELP_DETAILS.

tests/test_skills.py (new): unit tests that use FakeModelClient and tmp_path.

.claude/skills/grid-validation/SKILL.md, .claude/skills/reward-design/SKILL.md, .claude/skills/transition-testing/SKILL.md (ported, paths updated), .claude/skills/q-learning-training/SKILL.md (new).

lab/vacuum-robot/: context/vacuum-environment.md, environment.py, q_learning.py, tests/. The agent writes these during the demo run, not by hand.
README.md: a Project 2 section at the top.

logs/ (or a copy of .mini-coding-agent/skill_log.jsonl): the evidence from the Lab run.

## Order of work <!-- each step cites requirements -->

Failing tests first (tests/test_skills.py) for: discovery and skipping bad frontmatter (R1); no skills/ gives an unchanged prompt (R2); keyword extraction and the scoring math on a hand-computed example (R5, R6); threshold, top-k and tie order (R7, R9); the skill body appears in prompt() between prefix and memory (R8); load_skill works and rejects unknown names (R10, R11); log lines have every required field (R13, R14).

SkillLibrary: discovery and frontmatter parser, terms(text), score(prompt) that returns every skill's score and matched keywords, get(name), and log(event), which appends to .mini-coding-agent/skill_log.jsonl (R1, R5, R6, R9, R13, R14).

Wire up prompt time: in ask(), reset the active set, run the check, log it, activate the matches, print the console line, and record a history event (R4, R7, R15, R16). Add the active-skills section to prompt() (R8). Add the skill list to build_prefix() only when skills exist (R2, R3).

Wire up mid-task: add the load_skill tool (not risky) and its validation in validate_tool(), plus an example in tool_example(). Handle "already active" without tripping repeated_tool_call() (R10, R11, R14).

Delegation: pass the same SkillLibrary to the child agent in tool_delegate(). Assert that the child stays read_only with approval "never" (R12, R17).

CLI: add --skill-threshold, --max-skills and /skills, and update the help text (Design).

Skills: port the three Lab skills (fix paths to lab/vacuum-robot/, add keywords:), and write q-learning-training (R18).

Calibrate: run 8–10 realistic Lab prompts, read the scores in the log, and adjust the threshold or skill keywords until each prompt picks the right skill and off-topic prompts pick none. Record the final values in the README (R6, area of concern 1–2).

Run the Lab with the agent, a sequence of prompts at --approval ask, so the agent builds the environment, validates it, writes and runs the tests, records the hyperparameters, and trains Q-learning (R19, R20). Keep the log (R21).

README and video.

## Risks

The small model may not follow skill rules, or may write broken code. If so, break the Lab into smaller prompts, raise --max-steps and --max-new-tokens, or try a bigger Ollama model. Document whichever was used.

Adding a tool and a prefix section changes the prompt for every user. Mitigated by R2: with no skills, the prompt is byte-for-byte unchanged, and a test checks this.

Threshold tuning is guesswork. Mitigated by logging every skill's score, not just the winner, so tuning is based on data.

## Proof <!-- the tests that prove it is done -->

python -m pytest tests/ passes, both the original tests and test_skills.py (R1–R17).
.mini-coding-agent/skill_log.jsonl from the Lab run contains similarity_check lines with scores for all four skills, and skill_executed lines for both triggers (R13, R14, R21).
python -m pytest lab/vacuum-robot/tests passes, and python lab/vacuum-robot/q_learning.py prints a greedy policy that goes from (0,0) to (3,3) around the wall and avoids (3,1) (R19, R20).
Loading