docs: Adding a .goosehints guide (#279)

Co-authored-by: Angie Jones <jones.angie@gmail.com>

docs/configuration.md

@@ -17,7 +17,7 @@ default:
       requires: {}
 ```
 
-### Fields 
+### Fields
 
 #### provider
 
@@ -104,6 +104,7 @@ unit-test-gen:
 ```
 
 [jinja-guide]: https://jinja.palletsprojects.com/en/3.1.x/
+[using-goosehints]: https://block.github.com/goose/guidance/using-goosehints.html
 
 
 ## Adding a toolkit
@@ -145,5 +146,7 @@ Goose ships with the ability to read in the contents of a file named `.goosehint
 
 This file will be read into the Goose system prompt if it is present in the current working directory.
 
-> [!NOTE] 
+Check out the [guide on using .goosehints][using-goosehints] for more tips.
+
+> [!NOTE]
 > `.goosehints` follows [jinja templating rules][jinja-guide] in case you want to leverage templating to insert file contents or variables.

docs/guidance/getting-started.md

@@ -59,6 +59,8 @@ The following justfile shows our common commands:
 Write all code comments in French
 ```
 
+Check out the [guide on using .goosehints][using-goosehints] for more tips.
+
 ### Toolkits
 
 Toolkits expand Goose’s capabilities and tailor its functionality to specific development tasks. Toolkits provide Goose with additional contextual information and interactive abilities, allowing for a more comprehensive and efficient workflow.
@@ -139,3 +141,4 @@ goose session start --plan plan.md --args dep=pytest,repo=github
 [available-toolkits]: ../plugins/available-toolkits.md
 [providers]: ../plugins/providers.md
 [goose-plugins]:https://github.com/block-open-source/goose-plugins
+[using-goosehints]: https://block.github.com/goose/guidance/using-goosehints.html

docs/guidance/using-goosehints.md

@@ -0,0 +1,54 @@
+# Using `.goosehints` in Goose
+
+`.goosehints` are text files used within the Goose environment to provide additional context about your project and improve the communication between the developer and Goose. The use of `goosehints` ensures that Goose understands your requirements better and can execute tasks more effectively.
+
+>[!TIP]
+> **Developer toolkit required**
+>
+> To make use of the hints file, you need to have the `developer` toolkit [enabled](https://block.github.io/goose/plugins/using-toolkits.html).
+
+This guide will walk you through creating and using your `.goosehints` file to streamline your workflow with custom instructions and context.
+
+## Creating your `.goosehints` file
+You can place a `.goosehints` file in your current working directory or globally at `~/.config/goose/.goosehints`. This file can include any repeated instructions or contextual details relevant to your projects.
+
+A good time to consider adding a `.goosehints` file is when you find yourself repeating prompts, or providing the same kind of instructions multiple times.
+
+### Setting up hints
+
+The `.goosehints` file supports natural language and also follows [jinja templating rules][jinja-guide], so you can leverage templating to insert file contents or variables.
+
+Here are some ways people have used hints to provide additional context for Goose to follow:
+
+- **Decision-Making**: Specify if Goose should autonomously make changes or confirm actions with you first.
+
+- **Validation Routines**: Provide test cases or validation methods that Goose should perform to ensure changes meet project specifications.
+
+- **Feedback Loop**: Include steps that allow Goose to receive feedback and iteratively improve its suggestions.
+
+- **Point to more detailed documentation**: Indicate important files like `README.md`, `CONTRIBUTING.md`, or others that Goose should consult for detailed explanations.
+
+Like prompts, this is not an extensive list to shape your `.goosehints` file. You can include as much context as you need.
+
+Example `.goosehints file`:
+
+```jinja
+This is a simple example JavaScript web application that uses the Express.js framework. View [Express documentation](https://expressjs.com/) for extended guidance.
+
+Go through the README.md for information on how to build and test it as needed.
+
+Make sure to confirm all changes with me before applying.
+
+Use the following custom values when needed:
+{% include custom-config.js %}
+
+Run tests with `npm run test` ideally after each change.
+```
+
+## Best Practices
+
+- **Keep It Updated**: Regularly update the `.goosehints` file to reflect any changes in project protocols or priorities.
+- **Be Concise**: Make sure the content is straightforward and to the point, ensuring Goose can quickly parse and act on the information.
+
+
+[jinja-guide]: https://jinja.palletsprojects.com/en/3.1.x/

mkdocs.yml

@@ -120,6 +120,7 @@ nav:
       - "Getting Started": guidance/getting-started.md
       - "Managing Goose Sessions": guidance/managing-goose-sessions.md
       - "Quick Tips": guidance/tips.md
+      - "Using Goosehints": guidance/using-goosehints.md
       - "Applications of Goose": guidance/applications.md
       - "Goose in Action": guidance/goose-in-action.md
   - Plugins: